{"id":16371534,"url":"https://github.com/fox1t/typescript-microservice-starter","last_synced_at":"2025-03-16T15:33:24.132Z","repository":{"id":38351703,"uuid":"87536428","full_name":"fox1t/typescript-microservice-starter","owner":"fox1t","description":"A TypeScript starter-kit for building microservices with Node.js","archived":false,"fork":false,"pushed_at":"2023-03-05T17:50:15.000Z","size":639,"stargazers_count":65,"open_issues_count":7,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-16T00:54:49.501Z","etag":null,"topics":["boilerplate","microservice","nodejs","starter","starter-kit","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fox1t.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-07T10:52:50.000Z","updated_at":"2023-12-24T21:47:36.000Z","dependencies_parsed_at":"2024-10-11T03:08:47.524Z","dependency_job_id":"20d8045a-2406-4321-8910-c39bbecaa48f","html_url":"https://github.com/fox1t/typescript-microservice-starter","commit_stats":null,"previous_names":["nucleode/typescript-microservice-starter"],"tags_count":2,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fox1t%2Ftypescript-microservice-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fox1t%2Ftypescript-microservice-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fox1t%2Ftypescript-microservice-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fox1t%2Ftypescript-microservice-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fox1t","download_url":"https://codeload.github.com/fox1t/typescript-microservice-starter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221665599,"owners_count":16860290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boilerplate","microservice","nodejs","starter","starter-kit","typescript"],"created_at":"2024-10-11T03:08:39.645Z","updated_at":"2024-10-27T10:51:55.125Z","avatar_url":"https://github.com/fox1t.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ![Stampo](https://user-images.githubusercontent.com/6388707/58275504-7818c880-7d95-11e9-84af-f8aa50b93d5f.png) Stampo - TypeScript Microservice Starter\n\n[![styled with prettier](https://img.shields.io/badge/styled%20with-Prettier-blue.svg)](https://github.com/prettier/prettier)\n[![eslint](https://img.shields.io/badge/linted%20by-eslint-brightgreen.svg)](https://eslint.org)\n[![tested with tap](https://img.shields.io/badge/tested%20with-node--tap-yellow.svg)](https://github.com/tapjs/node-tap)\n![Node Build](https://github.com/nucleode/typescript-microservice-starter/workflows/Node%20Build/badge.svg)\n![Docker Build](https://github.com/nucleode/typescript-microservice-starter/workflows/Docker%20Build/badge.svg?branch=master)\n\n`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`).\n\nThere are only three steps you need to do to be productive after `Stampo` is initialized (follow the [Getting Started](#getting-started) section):\n1. Put your code inside the `./src` folder\n2. Put your tests inside the `./test` folder.\n3. Relax and enjoy coding!\n\n## Features\n\n* uses [esbuild](https://esbuild.github.io) and [`tsup`](https://tsup.egoist.sh) in dev mode for blazing fast builds and restarts\n* VS Code debugger configs in .vscode folder\n* recommended Dockerfile for secure Node.js production-ready images\n* most strict and backend specific [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) configuration\n* configured tests and reporters via [tap](https://node-tap.org)\n* [dotenv](https://github.com/motdotla/dotenv#readme) for development env vars\n\n## Getting Started\n### Clone the repo\n```\n$ git clone https://github.com/nucleode/typescript-microservice-starter.git {your_project_name}\n$ cd {your_project_name}\n```\n\n### Remove references to the original starter\n```\n$ rm -rf .git \u0026\u0026 npm init\n```\n\n### Initialize a git repository with your own\n```\n$ git init\n```\n\n### Install development dependencies\n```\n$ npm i\n```\n\n### Add remote origin and make an initial commit\n```\n$ git remote add origin git@github.com:{your_repository}.git\n$ git add .\n$ git commit -m \"Initial commit\"\n$ git push -u origin master\n```\n### Start the development server\n\n```\n$ npm run dev\n```\n\n## Included npm scripts\n`Stampo` includes a bunch of scripts that cover the most common scenarios for Node.js backend projects.\n\nThe commands must be run from the project's root folder.\n\n### `dev`\nIt runs the project in development mode. It uses [`tsup`](https://tsup.egoist.sh) 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](https://esbuild.github.io) and `tsc --noEmit` to build your code faster.\n```\n$ npm run dev\n```\n\n### `build`\nIt 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.\n```\n$ npm run build\n```\n\n### `start`\nIt 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`.\n```\n$ npm run start\n```\nThis 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.\n```\n$ node --enable-source-maps build/index.js\n```\n\n### `lint`\nIt uses [`eslint`](https://eslint.org) and [`prettier`](https://prettier.io) to lint the code. It checks `./src` and `./test` folders. Note: `prettier` is run as `eslint` plugin via [`eslint-plugin-prettier`](https://github.com/prettier/eslint-plugin-prettier).\n```\n$ npm run lint\n```\nIf you want to fix all of the fixable problems, run\n```\n$ npm run lint -- --fix\n```\n\n### `update`\nIt uses [npm-check](https://www.npmjs.com/package/npm-check) to help you upgrading your dependencies and never have any outdated and broken packages again.\n```\n$ npm run update\n```\n\n### `test`\nIt uses [`tap`](https://node-tap.org) to run tests. Since version 15 `tap` needs `ts-node` to run TS files, `Stampo` also includes it.\n```\n$ npm run test\n```\n\n### `test:watch`\nIt runs `tap` in [watch mode](https://node-tap.org/docs/watch/) with interactive repl.\n```\n$ npm run test:watch\n```\n\n### `test:report`\nIt runs tests and reports the results in the widely used `junit` format using [`tap-mocha-reporter`](https://www.npmjs.com/package/tap-mocha-reporter). The default `xunit` reporter can be changed to anyone from the [supported reporters list](https://node-tap.org/docs/reporting/). This command is mainly intended to be used in CI/CD environments. The generated `junit-testresults.xml` can be consumed by automatic reporting systems.\n\n## Env Vars\n`Stampo` includes [dotenv](https://github.com/motdotla/dotenv#readme). 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.\n\n## External typings augmentation\n`Stampo` is configured to allow you to extend typings of external packages using `./typings` folder. The logic behind it is based on [this](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/module-plugin-d-ts.html) 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](https://github.com/fox1t/fastify-websocket-router/tree/master/typings/fastify) you can find a real-world example.\n\n## Debugging Steps\n\n* run the `dev` script to start your application (`$ npm run dev`)\n* either\n  * use the VS Code included `attach` config for the best debugging experience\n  \u003cimg width=\"327\" alt=\"image\" src=\"https://user-images.githubusercontent.com/1620916/129894966-15385c33-da0c-4e00-9f6f-a8ddf966e63e.png\"\u003e\n\n  * use the provided debug URL in Chrome\n\n## Docker Support\n\n`Stampo` provides a `Dockerfile` that follows the best practices regarding Node.js containerized applications.\n* the application is run using a dedicated non-root user\n* the Dockerfile uses a dedicated build step\n\n\n### Build your docker image\n```\ndocker build -t my-project-name .\n```\n\n### Run your docker container\n\n```\ndocker run -p PORT:PORT my-project-name\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffox1t%2Ftypescript-microservice-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffox1t%2Ftypescript-microservice-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffox1t%2Ftypescript-microservice-starter/lists"}