Stampo - TypeScript Microservice Starter

Stampo is a friction-free features-complete boilerplate for building Node.js backend services and microservices with TypeScript. It works on Windows, Linux, and macOS and makes the developer productive in no time! It supports any Active LTS Node.js version (12.12.x, 14.x.x, 16.x.x).

There are only three steps you need to do to be productive after Stampo is initialized (follow the Getting Started section):

1. Put your code inside the ./src folder
2. Put your tests inside the ./test folder.
3. Relax and enjoy coding!

Features

• uses esbuild and tsup in dev mode for blazing fast builds and restarts
• VS Code debugger configs in .vscode folder
• recommended Dockerfile for secure Node.js production-ready images
• most strict and backend specific tsconfig.json configuration
• configured tests and reporters via tap
• dotenv for development env vars

Getting Started

Clone the repo

$ git clone https://github.com/nucleode/typescript-microservice-starter.git {your_project_name}
$ cd {your_project_name}

Remove references to the original starter

$ rm -rf .git && npm init

Initialize a git repository with your own

$ git init

Install development dependencies

$ npm i

Add remote origin and make an initial commit

$ git remote add origin [email protected]:{your_repository}.git
$ git add .
$ git commit -m "Initial commit"
$ git push -u origin master

Start the development server

$ npm run dev

Included npm scripts

Stampo includes a bunch of scripts that cover the most common scenarios for Node.js backend projects.

The commands must be run from the project's root folder.

dev

It runs the project in development mode. It uses tsup to watch the ./src/**/*.ts files, build and restart the server on save. It exposes the debugger on the default port (9229), ready to be used by the provided VS Code attach configuration. This script runs parallelly esbuild and tsc --noEmit to build your code faster.

$ npm run dev

build

It builds for production all files from the ./src to the ./build folder. It uses tsc directly and therefore checks types too. It also emits the source maps.

$ npm run build

start

It runs previously built code from the ./build folder. In addition, it uses --enable-source-maps flag for native source-maps support. Note: this flag is present in Node.js since version 12.12.x.

$ npm run start

This script is included only for convenience to test the production build locally on your dev machine. If needed, -r dotenv/config can be add to load the dev env. It is advised to run Node.js binary directly to avoid any overhead or sigterm propagation issues in production.

$ node --enable-source-maps build/index.js

lint

It uses eslint and prettier to lint the code. It checks ./src and ./test folders. Note: prettier is run as eslint plugin via eslint-plugin-prettier.

$ npm run lint

If you want to fix all of the fixable problems, run

$ npm run lint -- --fix

update

It uses npm-check to help you upgrading your dependencies and never have any outdated and broken packages again.

$ npm run update

test

It uses tap to run tests. Since version 15 tap needs ts-node to run TS files, Stampo also includes it.

$ npm run test

test:watch

It runs tap in watch mode with interactive repl.

$ npm run test:watch

test:report

It runs tests and reports the results in the widely used junit format using tap-mocha-reporter. The default xunit reporter can be changed to anyone from the supported reporters list. This command is mainly intended to be used in CI/CD environments. The generated junit-testresults.xml can be consumed by automatic reporting systems.

Env Vars

Stampo includes dotenv. You have to rename .env.example to .env and put your variables inside it. They will be automatically loaded when running $ npm run dev script.

External typings augmentation

Stampo is configured to allow you to extend typings of external packages using ./typings folder. The logic behind it is based on this official template. To augment a module, create a folder with the same module name you are augmenting and add an index.d.ts file inside it. Here you can find a real-world example.

Debugging Steps

• run the dev script to start your application ($ npm run dev)

• either

  • use the VS Code included attach config for the best debugging experience
  • use the provided debug URL in Chrome

Docker Support

Stampo provides a Dockerfile that follows the best practices regarding Node.js containerized applications.

• the application is run using a dedicated non-root user
• the Dockerfile uses a dedicated build step

Build your docker image

docker build -t my-project-name .

Run your docker container

docker run -p PORT:PORT my-project-name