Typescript Server Boilerplate on AWS Lambda

Production-ready Node.js v20 TypeScript app using MongoDB. Deployable to AWS Lambda using AWS SAM.

Compatible with Node.js >=19

This project does not use experimental flags such as --es-module-specifier-resolution or any custom loaders. Instead all TypeScript files have .js extensions in their import statements.

Table of Contents

• Features
• Quick Start
• Manual Installation
• Husky Setup
• AWS Lambda Deployment
• Inspirations
• License

Features

• ES2022: transpiles to ES2022 modules
• Static Typing: TypeScript static typing using typescript
• Hot Reloading: Concurrently Hot realoding with concurrently
• NoSQL database: MongoDB object data modeling using Mongoose
• Authentication and authorization: using passport
• Validation: request data validation using Joi
• Logging: using winston and morgan
• Testing: unit and integration tests using Vitest
• Error handling: centralized error handling mechanism
• API documentation: automatic OpenAPI spec generation with decorators from tsoa, served with swagger-ui-express
• Dependency injection: with InversifyJS
• Package management: with Yarn
• Environment variables: using dotenv and cross-env and AWS Secrets Manager
• Security: set security HTTP headers using helmet
• Santizing: sanitize request data against xss and query injection
• CORS: Cross-Origin Resource-Sharing enabled using cors
• Compression: gzip compression with compression
• AWS Lambda: IaC with AWS SAM
• CI: continuous integration with GitHub CI
• Git hooks: with husky and lint-staged
• Linting: with ESLint and Prettier
• Editor config: consistent editor configuration using EditorConfig
• Structured Commit Messages: with Commitizen
• Commit Linting: with CommitLint

Quick start

To clone this project, run:

npx @kazize/create-ts-starter-1

or,

npm init @kazize/ts-starter-1

and follow the prompts to setup the project.

Open .env and modify the environment variables (if needed).

Make sure you have MongoDB running locally. Then:

yarn dev

More steps:

• initialise your own fresh repository with git init

Manual Installation

Clone the repo.

Install the dependencies:

yarn install

Set the environment variables:

cp .env.example .env

Open .env and modify the environment variables (if needed).

Make sure you have MongoDB running locally. Then:

yarn dev

More steps:

• remove the existing .git folder
• rename the project folder from ts-starter-1 to something else, remove other references to ts-starter-1 from package.json and elsewhere.
• initialise your own fresh repository with git init

Husky Setup

After you have initialised your own fresh git repository, install the Husky git hooks provided with project.

yarn run husky install

Now husky tasks should run on git commit.

AWS Lambda Deployment

Make sure you have AWS and SAM CLIs installed locally.

Make sure you have MongoDB running on a cloud.

(Optional) Update the following in config object in package.json if necessary.

• s3BucketName
• region
• cloudFormationStackName

Create AWS Secrets Manager secrets like so:

• ts-starter-1/prod/JWT:secret
• ts-starter-1/prod/MONGODB_URL:url

If you change the prefix in the secrets above from ts-starter-1 to something else, then update them in sam-template.yaml as well.

Finally, run the following. Warning, this will create an S3 bucket and a CloudFormation Stack on your configured AWS account.

yarn setup

Inspirations

• saisilinus/node-express-mongoose-typescript-boilerplate
• hagopj13/node-express-boilerplate

License

MIT