TypeScript Seed for Node.js

This project is a starting point for Node.js applications using TypeScript, focused on productivity, organization, and best practices.

Features

• Ready-to-use scripts for running, watching, building, and testing;
• Separate configurations for debug, release, and test profiles;
• Easy dependency updates with pre-defined scripts (via npm-check-updates);
• Dependency injection with tsyringe;
• Debug and general configurations ready for Visual Studio Code;
• Unit testing with Jest (test explorer and debug support);
• Mock pattern for unit tests;
• Organized structure, ready to evolve;

Prerequisites

• Node.js v22 or higher;

Recommendations

• Develop using Visual Studio Code and the Jest extension;

Getting Started

1. Clone this repository:

   git clone https://github.com/paulosincos/node-typescript-seed
   cd node-typescript-seed

2. Install dependencies:

   npm install

3. Rename the project:
   • Edit package.json with your project's name and description.
4. (Optional) Remove example files:
   • Delete example files in src/ and tests/ as needed.
5. Start developing:
   • Create your source files in src/ and tests in tests/.

Project Structure

├── src/                # Main source code
├── tests/              # Unit tests and mocks
├── package.json        # Project configuration and scripts
├── tsconfig*.json      # TypeScript build profiles
├── jest.config.js      # Test configuration
└── README.md           # Documentation

Available Scripts

• npm start: Runs with debug configuration;
• npm run watch: Runs in watch mode;
• npm run start:release: Builds in release mode and runs;
• npm run build: Builds in release mode (output in dist);
• npm run build:debug: Builds in debug mode;
• npm run clear: Cleans built files (dist);
• npm test: Runs tests;
• npm run test:watch: Runs tests in watch mode;
• npm run test:coverage: Runs tests and generates coverage report;
• npm run update-packages: Updates dependencies;

See package.json for more commands and details.

Development Tips

• Use F5 key in VS Code to debug with breakpoints.
• Run tests directly from the test explorer.
• Use mocks to facilitate isolated tests.
• Keep your code organized in small, reusable modules.

Updating Dependencies

To update project dependencies:

npm run update-packages
npm install

Docker

This repository includes a multistage Dockerfile that builds the project inside a builder container and produces a minimal runtime image with the compiled dist output.

Build the image:

docker build -t my-app:latest .

Run the image:

docker run --rm my-app:latest

If your application listens on a network port, define the EXPOSE <PORT> option in Dockerfile and specify -p <PORT_MAP> in docker run ... command.

Docker Compose

This repository also includes a docker-compose.yml file at the project root to help run the application (and related services) in local containers.

Basic commands:

• Start containers:

docker compose up

• Stop and remove containers, networks and volumes created by Compose:

docker compose down

• Rebuild images and start (useful after code or dependency changes):

docker compose up --build

For more information and advanced usage, see the official Docker Compose documentation: Docker Compose docs.

Roadmap

• Integration tests;
• Use of Node.js native support for TypeScript;