In addition to a basic Lambda function and Express server, the example
directory includes a Swagger file, CloudFormation template with Serverless Application Model (SAM), and helper scripts to help you set up and manage your application.
This guide assumes you have already set up an AWS account and have the latest version of the AWS CLI installed.
- From your preferred project directory:
git clone https://github.com/CodeGenieApp/serverless-express.git && cd serverless-express/examples/basic-starter-api-gateway-v1
. - Update the
config
section ofpackage.json
with yours3BucketName
andregion
(optionally, change thecloudFormationStackName
). If the bucket you specify does not yet exist, the next step will create it for you. - (optional: domain) If you want to use a custom domain name for your application/API, specify it in the
config.domain
section ofpackage.json
. This example assumes the domain is registered in Route53 in the same account you're deploying the example to. - Run
npm run setup
- this installs the node dependencies, creates an S3 bucket (if it does not already exist), packages and deploys your serverless Express application to AWS Lambda, and creates an API Gateway proxy API. - (optional: domain) If you specify a domain, the example will create an SSL Certificate via Amazon Certificate Manager; create an API Gateway Domain Name record which maps the domain to the API and Stage; and create a Route53 HostedZone and RecordSet with an A record pointing at the API Gateway Domain Name's CloudFront Distribution.
- During deployment you should receive an email at one of the registered email addresses for the domain. Approve the SSL Certificate by clicking the link in the email. The stack creation will pause while waiting for this approval.
- Wait for stack creation to complete and update Route53 Domain Name to use the Name Servers from the created Hosted Zone NS Record (don't include the trailing '.') via the AWS console.
- It may take several hours before the DNS records propagate.
- After the setup command completes, open the AWS CloudFormation console https://console.aws.amazon.com/cloudformation/home and switch to the region you specified. Select the
ServerlessExpressStack
stack (or the stack name you specified forcloudFormationStackName
), then click theApiUrl
value under the Outputs section - this will open a new page with your running API. The API index lists the resources available in the example Express server (app.js
), along with examplecurl
commands. - (optional) To enable the
invoke-lambda
package.json
script
: copy theLambdaFunctionName
from the CloudFormation Outputs and paste it into thepackage.json
config
'sfunctionName
property. Runnpm run invoke-lambda
to invoke the Lambda Function with the payload specified inapi-gateway-event.json
.
See the sections below for details on how to migrate an existing (or create a new) Node.js project based on this example. If you would prefer to delete AWS assets that were just created, simply run npm run delete-stack
to delete the CloudFormation Stack, including the API and Lambda Function. If you specified a new bucket in the config
command for step 1 and want to delete that bucket, run npm run delete-bucket
.
To use this example as a base for a new Node.js project:
- Copy the files in the
examples/basic-starter-api-gateway-v1
directory into a new project directory (cp -r ./examples/basic-starter-api-gateway-v1 ~/projects/my-new-node-project
). If you have not already done so, follow the steps for running the example (you may want to first modify some of the resource names to something more project-specific, eg. the CloudFormation stack, Lambda function, and API Gateway API). - After making updates to
app.js
, simply runnpm run package-deploy
.
To migrate an existing Node server:
- Copy the following files from this directory:
api-gateway-event.json
,sam-template.yaml
, andlambda.js
. Additionally, copy thescripts
andconfig
sections ofexample/package.json
into your existingpackage.json
- this includes many helpful commands to manage your AWS serverless assets and perform basic local simulation of API Gateway and Lambda. If you have not already done so, follow the steps for running the example. - From your existing project directory, run
npm install --save @codegenie/serverless-express
. - Modify
lambda.js
to import your own server configuration (eg. changerequire('./app')
torequire('./server')
). You will need to ensure you export your app configuration from the necessary file (eg.module.exports = app
). This library takes your app configuration and listens on a Unix Domain Socket for you, so you can remove your call toapp.listen()
. - Modify the
CodeUri
property of the Lambda function resource insam-template.yaml
to point to your application directory (e.g.CodeUri: ./src
). If you are using a build tool (e.g. Gulp, Grunt, Webpack, Rollup, etc.), you will instead want to point to your build output directory. - Run
npm run package-deploy
.
To perform a basic, local simulation of API Gateway and Lambda with your Node server, update api-gateway-event.json
with some values that are valid for your server (httpMethod
, path
, body
etc.) and run npm run local
.
If you need to make modifications to your API Gateway API or other AWS resources, modify sam-template.yaml
and run npm run package-deploy
.
This example was written against Node.js 12
To update this example against the latest local changes to @codegenie/serverless-express:
npm pack ../..
npm install ./codegenie-serverless-express-4.0.0-rc.1.tgz
npm install --prefix ./src ./
npm run local