AWS Lambda in TypeScript
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.
- Full TypeScript codebase with strict type annotation - get as many compile time errors as possible.
- Deployment to AWS from the command line with Serverless - just run an npm script.
- Publishing to your custom Route53 domain name - for API URLs that live forever.
- Automated builds and CI with Travis CI on Linux and AppVeyor on Windows - get early feedback for every change.
- Offline execution - call your endpoints without deploying them to AWS.
- Minimal IAM policy to follow the principle of least privilege - because with great power comes great responsibility.
- Code analysis with TSLint and Codebeat - avoid dumb coding mistakes.
- Unit testing with Mocha, mocking with ts-mockito - be free to change your implementation.
- Test coverage report with Istanbul and Coveralls - so you know your weak spots.
- Integration testing after release - to verify your deployment.
- Generated Swagger documentation for the endpoints, which works well with SwaggerHub - the expected description of your API.
- Multiple layers in the code to separate concerns and independently test them - avoid monolith and complexity.
- Health check endpoints - to quickly test your service.
- Dependency checks and continuous update with David, Greenkeeper and Snyk- because the majority of your app is not your code.
- EditorConfig settings - for consistent coding styles between different editors.
- Sample CRUD implementation (in progress) - to see it all in action.
- Follows Linux Foundation Core Infrastructure Initiative Best Practices - for the open source community.
For updates, please check the CHANGELOG.
npm install serverless -g
Verify that Serverless was installed correctly:
- Setup AWS credentials:
Create a new IAM Policy in AWS using the
aws-setup/aws-policy.jsonfile. Note that the file contains placeholders for your
<your_deployment_bucket>. You can replace all those
*, 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:
- Customize the name of your service by changing the following line in the
- Customize the name of your domain by changing the following lines in the
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
What you can find in the code
Example CRUD endpoints
This project shows example Lambda function implementations with the following layers (see the
- Handler: The handler is the endpoint that is called by AWS when it executes your Lambda. See
- Controller: The controller is responsible for transforming any operation result to an HTTP response. See
- Service: The service is responsible for implementing the business logic, and provide the operation result. See
- Repository: The repository is responsible for providing the data for the service. See
All layers have unit tests with mocking the underlying layers.
- Response: The HTTP output for an endpoint call. It includes the HTTP status code, the response headers and the response body. The controller is responsible for building the response, using the
- Result: The outcome of the service call. It can be a success result or an error result.
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 endpoints
/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.|
Test the service locally
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.
Deploy to AWS
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.
Run unit tests
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.
Run integration tests
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.
View the documentation
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.
About the author
This project is maintaned by György Balássy.