A TypeScript starter-kit for building microservices with Node.js
MIT License
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):
./src
folder./test
folder.tsup
in dev mode for blazing fast builds and restartstsconfig.json
configuration$ git clone https://github.com/nucleode/typescript-microservice-starter.git {your_project_name}
$ cd {your_project_name}
$ rm -rf .git && npm init
$ git init
$ npm i
$ git remote add origin [email protected]:{your_repository}.git
$ git add .
$ git commit -m "Initial commit"
$ git push -u origin master
$ npm run dev
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.
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.
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.
run the dev
script to start your application ($ npm run dev
)
either
attach
config for the best debugging experienceStampo
provides a Dockerfile
that follows the best practices regarding Node.js containerized applications.
docker build -t my-project-name .
docker run -p PORT:PORT my-project-name