Express is the most popular web framework for Node.js, and you can now easily deploy your Express apps to AWS Lambda and API Gateway, with minimal changes. Since 20 September 2016, AWS API Gateway supports proxying requests to Lambda functions directly, which removed most of the restrictions that made running web frameworks inside Lambda difficult.
In this tutorial, you’ll learn how to deploy an existing Express application to AWS Lambda and API Gateway easily, with the help of the excellent
Preparing the Express app
Your Express application no longer needs to listen on a TCP port – API Gateway will handle the web requests. Remove the usual call to
app.listen, and just export the application
from the module, so it can be used in a Lambda function.
Creating a Lambda proxy wrapper
We’ll need a Lambda function to host the Express application, and send data between the app and the API Gateway. The
aws-serverless-express module knows how to translate between API Gateway requests and Express requests and responses, so we’ll use that. Claudia has a convenient command to generate the wrapper function, so you don’t have to write it manually.
Make sure you’re using Claudia 2.1.0 or later, then execute this command line in your project directory (replace
app with the name of the main Express application module):
This will add
aws-serverless-express to your project dependencies, and create the file containing your Lambda function. By default, the file will be called
lambda.js. You can change the file name using
--proxy-module-name <module name>
Deploying to AWS
We can now deploy the Lambda function to AWS, and create the proxy API. With Claudia 2.0, you can create proxy APIs easily – just add the
--deploy-proxy-api option while creating the function. For
--handler, use the module name that you just generated (so
lambda by default) and add
The command will send your app to Lambda and print out a URL where you can access it. That’s pretty much it.
To see this in action, check out the example project.
You can customise the name of the Lambda function and control some other parameters, such as maximum allowed memory and timeouts, by adding parameters to
claudia create. To learn how to manage different versions for development, production and testing, see the Managing Lambda Versions tutorial. For more information on deploying proxy APIs, check out the Deploying Proxy APIs tutorial.
There are two big limitations of the platform that are important to note, as they won’t prevent you from deploying the code, but it will just not work:
- API Gateway does not support sending binary content. That’s just not possible at the moment. As a workaround, put binary assets (such as images), somewhere else – for example S3, or CloudFront. For performance reasons you should put binary content on a static asset server or CDN anyway.
- Lambda is essentially stateless. Two requests from the same user might hit the same virtual machine container, but they might not. There is no way for you as a customer to influence that, so apps relying on saving state in-memory on the server will be broken in lots of wonderful ways. As a workaround, you’ll have to save state in a database (such as DynamoDB) or move it to the client.