This sample uses the Serverless Application Framework to implement an AWS Lambda function in TypeScript, deploy it via CloudFormation, and publish it through API Gateway.
IMPORTANT! Since I am not working on any AWS Lambda project at the moment I temporarily suspended the maintenance of this project, because I cannot closely follow the evolution of the platform and validate that this project is still working and useful. I recently turned off Greenkeeper, because it often submitted broken PRs that failed on CI, and checking and fixing those took more time than I can spend on this project. I still believe that this sample has value and I am planning to update it for my next Lambda project. Thanks for understanding.
For updates, please check the CHANGELOG.
npm install serverless -g
Verify that Serverless was installed correctly:
Create a new IAM Policy in AWS using the
aws-setup/aws-policy.json file. Note that the file contains placeholders for your
You can replace all those
Resource ARNs with
*, if you intentionally don't want to follow the Principle of Least Privilege, but want to avoid permission issues.
(If you prefer minimal permissions, just like me, you may want to follow Issue 1439: Narrowing the Serverless IAM Deployment Policy. )
Create a new IAM User for Programmatic Access only, assign the previously created policy to it, and get the Access Key ID and the Secret Access Key of the user.
Save the credentials to the
serverless config credentials --provider aws --key YOUR_ACCESS_KEY --secret YOUR_SECRET_KEY
Unfortunately on Windows you will need an Administrator user to run the Serverless CLI.
You can read more about setting up AWS Credentials on the AWS - Credentials page of the Serverless Guide.
Clone this repository.
Install the dependencies:
custom: customDomain: domainName: serverless-sample.balassy.me certificateName: serverless-sample.balassy.me
NOTE: You must have the certificate created in AWS Certificate Manager before executing this command. According to AWS to use an ACM certificate with API Gateway, you must request or import the certificate in the US East (N. Virginia) region.
If you don't want to publish your API to a custom domain, remove the
serverless-domain-manager from the
plugins section, and the
customDomains entry from the
custom section of the
This project shows example Lambda function implementations with the following layers (see the
All layers have unit tests with mocking the underlying layers.
To understand the code, open
src/cities/cities.ts, find the
getCity function and follow the call chain.
src/swagger folder contains the
/swagger.json endpoint which exports the documentation of the API in Swagger format. Call the endpoint after deploying your API and paste the response JSON into the Swagger Editor to display it in a friendly way.
You can also reference the
swagger.json URL when you publish your documentation via SwaggerHub, as you can see on the SwaggerHub page of this sample: https://app.swaggerhub.com/apis/balassy/serverless-sample.
/health/check and the
/health/check/detailed endpoints in the
src/health folder are provided to run quick checks on your API after deployment.
||Runs all code analysis tools, including linters and unit tests.|
||Runs all analysis tools, creates the deployment package, installs it on AWS and finally runs the integration tests.|
||Runs the service locally, so you can call your API endpoints on http://localhost.|
||Runs all pre-deploy analysis and creates the deployment package, but does not install it onto AWS.|
||Removes all tool-generated files and folders (build output, coverage report etc.). Automatically runs as part of other scripts.|
||Creates the domain in Route53. Required to manually execute once.|
||Runs the static code analyzers. Automatically runs before deployment.|
||Runs the unit tests. Automatically runs before deployment.|
||Runs the integration tests. Automatically runs after deployment.|
To invoke the Lambda function locally, run: This command requires Administrator privileges on Windows!
serverless invoke local --function getCity
To run the service locally, run: This command requires Administrator privileges on Windows!
This command will not terminate, but will keep running a webserver that you can use to locally test your service. Verify that the service runs perfectly by opening the
http://localhost:3000 URL in your browser. The console window will log your requests.
You can modify your code after running this command, Serverless will automatically recognize the changes and recompile your code.
To create a custom domain for your service in AWS, run this command once: This command requires Administrator privileges on Windows!
npm run deploy:init
According to AWS, after this command it may take up to 40 minutes to initialize the domain with a CloudFront distribution. In practice it usually takes about 10 minutes.
To deploy the service to AWS, run: This command requires Administrator privileges on Windows!
or you can use the NPM script alias, which is recommended, because it runs the analysers (linter + tests) before deployment, and integration tests after deployment:
npm run deploy
Verify that the deployment is completed successfully by opening the URL displayed in your console window in your browser. To see all resources created in AWS navigate to CloudFormation in the AWS Console and look for the stack named with the name of your service you specified in Step 6.
To download the Swagger description of your service, open the following URL in your browser:
Note that this endpoint always downloads the Swagger documentation from the live, published API, even if the code is running locally!
If you don't want to deploy your code, just want to peek into the deployment package, you can run:
npm run build
This command is not only an alias to
serverless package, but also runs all analyzers that the deploy process also runs.
To check your codebase with TSLint, run:
npm run lint
The linter automatically checks your code before deployment, so you don't need to run it manually.
To check your code with unit tests, run:
The unit tests are automatically running before deployment, so you don't need to run them manually.
To verify that your deployment completed successfully, run:
npm run test:integration
The integration tests are automatically running after deployment, so you don't need to run them manually.
To view the generated Swagger documentation, deploy your API or start it locally, and then call the
EPERM: operation not permitted, symlink 'C:\Git\aws-lambda-typescript\node_modules' -> 'C:\Git\aws-lambda-typescript\.build\node_modules'
On Windows you need Administrator privileges to run
serverless commands (see Issue 23).
Your feedback is more than welcome, please send your suggestions, feature requests or bug reports as Github issues.
Contributions of all kinds are welcome, please feel free to send Pull Requests. As they are requirements of successful build all linters and tests MUST pass, and also please make sure you have a reasonable code coverage for new code.
Thanks for your help in making this project better!
Thanks to Shovon Hasan for his article on Deploying a TypeScript + Node AWS Lambda Function with Serverless.
This project was created by György Balássy.