My batteries included TypeScript starter for 2025

Table of contents

Intro

Internet is full of project templates, and you can generate unlimited amount more with AI tools. Yet, I like to start my projects from a known baseline, which I understand. All the moving parts are chosen and configured by me, so I can edit the setup without fearing that everything will collapse like a house of cards.

In my experience, a solid baseline will also help AI tools such as GitHub Copilot to offer more relevant completions.

I changed quite a lot in this iteration of the template, for example Jest was ousted by Vitest, and production-ready Docker image can be built. Additionally few other dependencies were removed to simplify the setup, all thanks to development on few utilized projects. Let’s dig in.

What’s inside

This is My Batteries included TypeScript starter for 2025, with:

• 🟩 Node.js 22
• ✏️ TypeScript 5.7
• 📚 ECMAScript Modules
• ⚙️ NPM package manager
• ⚗️ code linting & formatting with ESLint & Prettier
• 🚥 testing with Vitest
• 🔬 VS Code configuration for debugging and testing
• 🔥 hot reloading
• 📦 production bundling with esbuild
• 🐳 optional production ready Docker image creation
• 🔁 GitHub Actions workflow to run code quality checks and tests

What’s not inside

• Monorepo setup
• Any particular app’s source code

✅ Prerequisites

• Make sure you have Node.js 22 installed. This is built, configured and tested with Node.js 22.
• If you want to use VS Code, make sure the following extensions are installed:
  • ESLint
  • Vitest

📌 Getting started

How to use this template?

1. Make sure prerequisites are met.
2. Download the repository as zip so you don’t have to deal with git history of this repository.
3. Delete package-lock.json.
4. Replace janik6n in package.json with your own username, along with other info.
5. Install dependencies by running npm install on the project root directory.
6. Start developing. See below for available scripts.

Available scripts

⚙️ Run development server

To run TypeScript to JavaScript transpiling and to run transpiled ./dist/index.mjs run npm run dev. Watch mode (a.k.a. hot reloading) is available with npm run dev:watch. Development serving is handled with tsx.

🚥 Run tests

Test are run with Vitest, and different test scenarios are handled with Vitest workspaces.

To run tests, you have a several of options:

• Run all tests with npm run test.
• Include coverage report with npm run test:cov.
• Run unit tests with npm run test:unit. This runs all tests which are in files with name *.unit.test.ts.
• Run integration tests with npm run test:integration. This runs all tests which are in files with name *.integration.test.ts.
• Run end-to-end (e2e) tests with npm run test:e2e. This runs all tests which are in files with name *.e2e.test.ts.
• Run unit and integration tests in watch mode with npm run test:watch in separate terminal session than your development server.
• Run unit and integration tests in CI environment with npm run test:ci. Note: this script exists so it’s easy to configure which tests are run in CI.

⚗️ Format source code

Format the source code with Prettier by running npm run format.

⚗️ Lint source code

Lint a.k.a. check the formatting of the source code with npm run lint.

The idea is to run ESLint & Prettier on VS Code as you code, so this script is mostly for code quality checks in CI. Prettier is run as ESLint plugin.

📦 Build production bundle

Build the production bundle with esbuild by running npm run build. Build is configured in build.js.

Build command explained: "build": "rimraf ./dist && npx tsc --noEmit && node build.js":

• rimraf ./dist: delete ./dist folder
• npx tsc --noEmit: run type checks
• node build.js: build and bundle with esbuild, which does not do type checking, but it creates nice small bundles

Sometimes it’s necessary to see the built app with just transpiling without bundling. This can be accomplished with npm run build:tsc.

⚙️ Run production bundle

Run the built app with npm run start.

🐳 Build as container

Run npm run build:container to build the app as Docker container. Multi-stage build is used to minimize the production image size. Debian-based image is used to minimize the risk of compatibility issues.

🐳 Run as container

Run the containerized app with npm run start:container.

Links

You can find the template on GitHub janik6n/typescript-starter: Batteries included TypeScript starter for 2025.