README.md

Serverless Micoservices w/ GraphQL Template

A template for a Serverless Framework microservices architecture based on the nx-serverless-template by sudokar.

Table of contents

• Whats Included
• Template Layout
• Prerequisites
• Usage
• Further help
• Contribution
• Support
• Maintainer
• License

Whats Included

• A template project layout using latest version of Nx and Servrless Framework
• An easy to use workspace generator to generate a template/service with Serverless Framework files and related Nx configuration
• Configured with a basic AWS provider that can be easily adopted to any cloud provider
• Serverless Offline microservices architecture support

How does this differ from the original template?

The original template is phenomenal, but I was aiming for some additional customizations and different core libraries. Specifically:

• This version uses esbuild instead of webpack
• This version provides some common utility functions for a microservices architecture
• Upstream used Nx Cloud and some other 3rd party tools where this version uses just GitHub Actions
• This version provides opinionated public-api and background-jobs services for consumption.

Template Layout

.
├── services/    # each serverless configuration/template and its associated files
├── libs/      # shared libraries
├── tools/
├── README.md
├── jest.config.ts
├── jest.preset.ts
├── nx.json
├── package.json
├── serverless.common.yml  # shared serverless configuration
├── tsconfig.base.json
├── workspace.json
├── .editorconfig
├── .eslintrc.json
├── .gitignore
├── .husky              # git hooks
├── .nvmrc
├── .prettierignore
├── .prettierrc
├── docker-compose.yml

Prerequisites

• Node.js 16 - nvm recommended
• Yarn
• Serverless Framework v3
• 💅 Code format plugins
  • Eslint
  • Prettier
  • EditorConfig
• Jest for testing

Usage

Install project dependencies

yarn

Setup and run infrastructure

All needed services, such as databases, are managed via Docker. When working in this project, it is recommended that you start all the infrastructure. When you're not working on the project, you should stop all the infrastructure.

# Creates the docker container and starts it.
yarn infrastructure:setup

# Stops the docker container and deletes it.
yarn infrastructure:teardown

# Starts the docker container. Requires the container to exist.
yarn infrastructure:start

# Stops the docker container. Requires the container to exist.
yarn infrastructure:stop

Generate a new service

yarn workspace-generator service <SERVICE_NAME>

Generate a new library

yarn workspace-generator lib <LIBRARY_NAME>

Packaging services

# Package a single service
yarn build <SERVICE_NAME>


# Package all services afffected by a change
yarn affected:build


# Package all services
yarn all:build

Pass the --stage=<STAGE_NAME> flag if you're creating a build for a specific environment.

Deploying services

# Deploy a single service to a stage
yarn deploy <SERVICE_NAME> --stage=<STAGE_NAME>

# Deploy all services to a stage
yarn deploy:all --stage=<STAGE_NAME>

Removing deployed service

# Remove a single service from a stage
yarn remove <SERVICE_NAME> --stage=<STAGE_NAME>

# Remove all services for a stage
yarn remove:all --stage=<STAGE_NAME>

Run tests

# Run tests for a single service or library
yarn test <SERVICE_OR_LIB_NAME>

# Run tests for all services or libraries affected by a change
yarn test:affected

# Run all tests
yarn test:all

Analyze function bundles

When building serverless applications, it's important to understand your memory footprint due to Lambda's memory settings as you can experience unexpected errors. As such, the following script can be used to understand the memory footprint of your individual functions:

yarn analyze <SERVICE_NAME> --function=<FUNCTION_NAME>

This will open the results in a new tab in your browser with the results using esbuild visualizer.

Run offline / locally

• To run a single service

yarn serve <SERVICE_NAME>

Understand your workspace

yarn dep-graph

Further help

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

Contribution

Found an issue? Feel free to raise an issue with information to reproduce. Pull requests are welcome to improve.

Support

If you like this template, please go support sudokar as this template would not have been possible without their original work. However, you can always leave this version a star ⭐. 😄

Maintainer

This version of the template is authored and maintained by dustinsgoodman

License

MIT