nachimk / sls_backend_template

Backend starter template for a NestJS GraphQL API Clean Architecture on AWS Lambda with security and performance best practices

Production Ready Serverless NestJS

This project contains a backend starter template for running NestJS GraphQL APIs on AWS Lambda with security and performance best practices.

Features

• GraphQL configuration (Code-first approach)
• Prisma Database config with migrations
• Docker database for local development
• AWS Deployment with Serverless Framework
• AWS Lambda NodeJS 18x configuration and optimizations
• GitHub actions for CI/CD

Not included

• Authentication/Authorization

Technology Choices

NestJS

• Opinionated, mature backend framework with active community
• Supports dependency injection out of the box
• First-class typescript support

GraphQL

• Provides a query language that lets clients specify the data they need
• Strong support in frontend frameworks like React

AWS Lambda

• Pay-per-use pricing is ideal for early-stage startups where traffic and access patterns are unknown
• Cold starts can be minimized by keeping package bundles small, caching server between invocations and keeping lambdas warm

Serverless framework

• Strong community of plugins and supports for NodeJS/Typescript

Prisma

• ORM with great developer experience
• Excellent Typescript support

Supabase

• Hosted serverless Postgres database

Dependencies

• NodeJS
• NVM brew install nvm
• Yarn
• Docker
• VSCode
• AWS Account

Setup

Local Development

1. Create a .env file using .env.example as an example

2. nvm use

3. yarn install

4. Launch Supabase in Docker with npx supabase start

5. Run database migrations locally in a separate terminal if it's a first time setup with npx prisma migrate dev

6. Seed the database with npx prisma db seed

7. Start the NestJS server with yarn start:dev

8. Call the endpoints in requests.http to test the API.

Integration tests

yarn test:e2e

Webpack bundling

yarn build # with webpack

# run binary locally
node dist/main.js

Serverless Offline

Test AWS Lambda packaging and run locally with:

npx serverless offline

AWS Deployment

Note - create all AWS and Supabase resources in the us-east-1 AWS region.

1. Setup your AWS Credentials for deployments

2. Create a free-tier Supabase database.

3. Create an AWS SSM Parameter in the AWS console named /dev/database/url with the secure string type and save the DB connection string.

   Confirm it exists with:

   aws ssm get-parameter --name /dev/database/url --with-decryption
   

4. Install dependencies:

   nvm use 18
   yarn install
   

5. Deploy the app to AWS:

   npx serverless deploy
   

Update requests.http with the output of the deployment to call the API.

Database Migrations

# create migrations
npx prisma migrate dev --name <MIGRATION_NAME>

# run migration
npx prisma migrate dev

# reset development database
npx prisma migrate reset

Note - an ERD diagram for the database schema will be generated under /docs - see diagram.

Production Database Migrations

Production database migrations should be run in a CI/CD pipeline but can also be run locally with:

npx prisma migrate deploy

See the Prisma docs for more information.

Resources

• Serverless Framework
• NestJS
• Prisma
• Supabase
• GraphQL

Suggested SaaS integrations

Auth

• Auth0

Monitoring

• Lumigo