Skip to content

Commit 504cef6

Browse files
ajeetchaulagainajeetchaulagain
committed
Update readme
1 parent 4e2d354 commit 504cef6

2 files changed

Lines changed: 88 additions & 67 deletions

File tree

‎README.md‎

Lines changed: 88 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,119 @@
1-
<p align="center">
2-
<a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
3-
</p>
4-
5-
[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456
6-
[circleci-url]: https://circleci.com/gh/nestjs/nest
7-
8-
<p align="center">A progressive <a href="http://nodejs.org" target="_blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
9-
<p align="center">
10-
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
11-
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
12-
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/dm/@nestjs/common.svg" alt="NPM Downloads" /></a>
13-
<a href="https://circleci.com/gh/nestjs/nest" target="_blank"><img src="https://img.shields.io/circleci/build/github/nestjs/nest/master" alt="CircleCI" /></a>
14-
<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
15-
<a href="https://opencollective.com/nest#backer" target="_blank"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
16-
<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
17-
<a href="https://paypal.me/kamilmysliwiec" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg" alt="Donate us"/></a>
18-
<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://img.shields.io/badge/Support%20us-Open%20Collective-41B883.svg" alt="Support us"></a>
19-
<a href="https://twitter.com/nestframework" target="_blank"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow" alt="Follow us on Twitter"></a>
20-
</p>
21-
<!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
22-
[![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
23-
24-
## Description
25-
26-
[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
27-
28-
## Project setup
1+
# NestJS on AWS Lambda with CDK
292

30-
```bash
31-
$ npm install
3+
Reference implementation of a NestJS application running on AWS Lambda, using AWS CDK for infrastructure, HTTP API Gateway as the entry point, and GitHub Actions for CI/CD.
4+
5+
> Companion repository for the blog post **[A Practical Guide to Running Serverless NestJS on AWS Lambda with AWS CDK and GitHub Actions](https://deploy-preview-222--ajeetchaulagain.netlify.app/blog/nestjs-aws-serverless/)**.
6+
7+
## Architecture
8+
9+
![Architecture](docs/nestjs-serverless.drawio.png)
10+
11+
A client sends an HTTP request to API Gateway, which forwards it to the Lambda function using proxy integration. The Lambda function bootstraps the NestJS application, with production dependencies resolved from the attached Lambda Layer.
12+
13+
## Stack
14+
15+
- **Runtime:** Node.js 24 / NestJS
16+
- **Infrastructure:** AWS CDK (TypeScript)
17+
- **API:** HTTP API Gateway (v2)
18+
- **Lambda Layer:** Production `node_modules` separated from application code
19+
- **CI/CD:** GitHub Actions
20+
21+
## Project Structure
22+
23+
```
24+
├── src/ # NestJS application source
25+
│ ├── lambda.ts # Lambda handler — adapts NestJS for Lambda execution model
26+
│ └── main.ts # Local development entry point
27+
├── infra/ # AWS CDK infrastructure (separate npm project)
28+
│ ├── bin/infra.ts # CDK app entry point
29+
│ └── lib/infra-stack.ts # Stack definition — Lambda, Layer, API Gateway
30+
├── layer/ # Lambda layer (gitignored, generated at build time)
31+
│ └── nodejs/
32+
│ └── node_modules/ # Production-only dependencies
33+
└── .github/workflows/
34+
└── deploy.yml # GitHub Actions deployment pipeline
3235
```
3336

34-
## Compile and run the project
37+
## Prerequisites
38+
39+
- Node.js 24
40+
- AWS CLI configured (`aws configure`)
41+
- AWS CDK bootstrapped in your target account/region (`cdk bootstrap`)
42+
43+
## Getting Started
44+
45+
Install root dependencies and start the development server:
3546

3647
```bash
37-
# development
38-
$ npm run start
48+
npm install
49+
npm run start:dev
50+
```
51+
52+
The application runs locally on `http://localhost:3000`.
53+
54+
> `infra/` is a separate npm project with its own `package.json`. Its dependencies are installed separately — see the deployment steps below.
55+
56+
## Build
3957

40-
# watch mode
41-
$ npm run start:dev
58+
Run the following before deploying:
4259

43-
# production mode
44-
$ npm run start:prod
60+
```bash
61+
# compile TypeScript → dist/
62+
npm run build
63+
64+
# install production dependencies into layer/nodejs/node_modules/
65+
npm run build:lambda-layer
4566
```
4667

47-
## Run tests
68+
## Deploying Locally
69+
70+
Before deploying, make sure your AWS credentials are configured locally. If you haven't set this up yet, the blog post covers the AWS CLI setup and CDK bootstrapping steps in detail.
4871

4972
```bash
50-
# unit tests
51-
$ npm run test
73+
aws configure
74+
```
5275

53-
# e2e tests
54-
$ npm run test:e2e
76+
Install the CDK dependencies inside `infra/` — this is a separate npm project from the root and needs its own install:
5577

56-
# test coverage
57-
$ npm run test:cov
78+
```bash
79+
cd infra && npm install
5880
```
5981

60-
## Deployment
82+
The stack is defined in `infra/lib/infra-stack.ts`. It provisions the Lambda function, attaches the Layer, and wires up HTTP API Gateway. Synthesize the CloudFormation template first to validate the stack without touching AWS:
6183

62-
When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information.
84+
```bash
85+
npx cdk synth
86+
```
6387

64-
If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps:
88+
Then deploy:
6589

6690
```bash
67-
$ npm install -g @nestjs/mau
68-
$ mau deploy
91+
npx cdk deploy
6992
```
7093

71-
With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.
94+
After a successful deploy, the API URL is printed in the terminal:
7295

73-
## Resources
96+
```
97+
Outputs:
98+
InfraStack.HttpApiUrl = https://abc123.execute-api.us-east-1.amazonaws.com/
99+
```
74100

75-
Check out a few resources that may come in handy when working with NestJS:
101+
## Deploying via GitHub Actions
76102

77-
- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework.
78-
- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy).
79-
- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/).
80-
- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks.
81-
- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com).
82-
- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com).
83-
- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs).
84-
- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com).
103+
The workflow at `.github/workflows/deploy.yml` triggers automatically on push to `main` and on pull requests.
85104

86-
## Support
105+
Add the following to your repository under **Settings → Secrets and variables → Actions**:
87106

88-
Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
107+
| Name | Type | Description |
108+
| ----------------------- | -------- | ------------------------------------ |
109+
| `AWS_ACCESS_KEY_ID` | Secret | AWS IAM access key |
110+
| `AWS_SECRET_ACCESS_KEY` | Secret | AWS IAM secret key |
111+
| `AWS_REGION` | Variable | Target AWS region (e.g. `us-east-1`) |
89112

90-
## Stay in touch
113+
> `AWS_REGION` is stored as a Variable rather than a Secret so it remains visible in workflow logs.
91114
92-
- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
93-
- Website - [https://nestjs.com](https://nestjs.com/)
94-
- Twitter - [@nestframework](https://twitter.com/nestframework)
115+
Once the workflow file is merged to `main`, pushes and pull requests will trigger the pipeline automatically.
95116

96117
## License
97118

98-
Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).
119+
MIT

‎docs/nestjs-serverless.drawio.png‎

93 KB
Loading

0 commit comments

Comments
 (0)