README.md

Nx Serverless

The Ultimate Monorepo Starter for Node.js Serverless Applications

✅  First-Class Typescript Support
✅  DynamoDB Single Table Design
✅  Shared API Gateway
✅  Environments Configuration
✅  CORS
✅  JWT Auth Middleware
✅  Http Params Validation
✅  Typed Proxy Handlers
✅  Auto Generators
✅  Localstack
✅  ESLint
✅  Jest
✅  Github Actions

---

Prerequisites

• Docker
• Node.js

Getting Started

• Run git clone https://github.com/ngneat/nx-serverless.git your-app-name
• Run npm install
• Run npm run localstack ( Check that it works by going to http://localhost:4566/health)
• Run npx nx deploy core --stage local to create the table
• Update the environment files based on your configuration
• Run npm run serve

About the App

The application contains three services:

Auth Service:

The auth service is responsible for authentication. It exposes one route for signing up:

curl --request POST 'http://localhost:3001/dev/auth/sign-up' \
--data-raw '{
    "email": "[email protected]",
    "name": "Netanel Basal"
}'

The request returns a JWT, which is used for accessing protected routes.

Users Service:

The users service is responsible for managing users. It exposes one route:

curl 'http://localhost:3003/dev/user' --header 'Authorization: token TOKEN'

The request returns the logged-in user.

Todos Service:

The todos service is responsible for managing todos. A user has many todos. It exposes CRUD routes:

// Get user todos
curl 'http://localhost:3005/dev/todos' --header 'Authorization: token TOKEN'

// Get a single todo
curl 'http://localhost:3005/dev/todos/:id' --header 'Authorization: token TOKEN'

// Create a todo
curl --request POST 'http://localhost:3005/dev/todos' \
--header 'Authorization: token TOKEN'
--data-raw '{
    "title": "Learn Serverless"
}'

// Update a todo
curl  --request PUT 'http://localhost:3005/dev/todos/:id' \
--header 'Authorization: token TOKEN' \
--data-raw '{
    "completed": true
}'

DynamoDB GUI

Download NoSQL Workbench for DynamoDB and connect to http://localhost:4566.

Commands

nx serve <service-name>
nx deploy <service-name>
nx remove <service-name>
nx build <service-name>
nx lint <service-name>
nx test <service-name>

// Use different enviroment
NODE_ENV=prod nx deploy <service-name> 
NODE_ENV=stg nx deploy <service-name> 

// Run only affected
nx affected:test
nx affected:deploy

Generators

// Generate a service
yarn g:service tags

// Generate handler
yarn g:handler handler-name

// Generate http handler
yarn g:http-handler create-tag

// Generate a model
yarn g:model tag

---

CI/CD Pipeline with Github Actions

The pipeline has been configured to run everytime a push/pull_request is made to the main branch. You should uncomment the ci.yml workflow.

Workflow Steps

• Checkout: The checkout action is used to checkout the source code.

• Node setup: The setup-node action is used to optionally download and cache distribution of the requested Node.js version.

• lint and test: The lint and test runs only on affected projects.

• Configure AWS credentials: The credentials needed are AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY and should be set as Github secrets.

• Each branch should be prefixed with the environment name. For example, if we have a stg-feature-name branch and open a pull request to the main branch, it will set NODE_ENV to stg and deploy to this environment.

By merging the pull request to the main branch, NODE_ENV is set to prod, and the deployment is done to production.

The workflow file can have as many environments as you need.

Further help

• Visit Serverless Documentation to learn more about Serverless framework
• Visit Nx Documentation to learn more about Nx dev toolkit
• Visit LocalStack to learn more about it

Contribution

Found an issue? feel free to raise an issue with information to reproduce.

Pull requests are welcome to improve.

License

MIT

This project is a fork of nx-serverless

Monster icons created by Smashicons - Flaticon