node-ts-starter

⚡ A fast, modern, TypeScript-powered Node.js starter template that runs out of the box. No setup pain. No fighting configs. Just clone and start coding.

Features

⚙️ Modern TypeScript Setup

• Strict TypeScript configuration out of the box
• Path aliases configured (@/* for clean imports)
• Latest ES modules support

🧪 Testing Ready

• Jest pre-configured with TypeScript support
• Example tests included
• Watch mode for TDD workflow

🔥 Developer Experience

• Hot reload with tsx for instant feedback
• Native .env file loading with dotenv
• Clean project structure
• Automated cleanup script to remove template boilerplate

Installation

Using degit (Recommended)

npx degit clebertmarctyson/node-ts-starter my-project
cd my-project
pnpm install

Using Git Clone

git clone https://github.com/clebertmarctyson/node-ts-starter.git my-project
cd my-project
rm -rf .git
pnpm install

Quick Start

The template works immediately after installation. Test it first before cleaning up:

# Start development server with hot reload
pnpm dev

# Run example tests
pnpm test

# Build for production
pnpm build

# Run production build
pnpm start

Once you've verified everything works, run the cleanup script to prepare for your project:

pnpm clean

Project Structure

my-project/
├── src/
│   ├── index.ts           # Main entry point
│   ├── lib/
│   │   └── math.ts        # Example utilities (removed by cleanup)
│   └── tests/
│       └── math.test.ts   # Example tests (removed by cleanup)
├── assets/
│   └── node-ts-starter-banner.png  # Removed by cleanup
├── dist/                  # Compiled output (generated)
├── .env.example           # Environment template (renamed by cleanup)
├── clean.ts               # Cleanup script
├── tsconfig.json          # TypeScript configuration
├── jest.config.js         # Jest configuration
└── package.json

Commands

Development

Command	Description
pnpm dev	Start development server with hot reload
pnpm build	Compile TypeScript to JavaScript
pnpm start	Run compiled production build

Testing

Command	Description
pnpm test	Run all tests once
pnpm test:watch	Run tests in watch mode

Utilities

Command	Description
pnpm clean	Remove template files and prepare project

Cleanup Script

The cleanup script transforms this template into your own project. It's optional but recommended when you're ready to start developing.

What It Does

The cleanup script:

• ✅ Renames .env.example → .env
• ✅ Deletes assets/ directory (banner images, etc.)
• ✅ Removes example code (src/lib/math.ts)
• ✅ Deletes example tests (src/tests/math.test.ts)
• ✅ Cleans up imports in src/index.ts
• ✅ Replaces README with a blank starter template
• ✅ Updates package.json with your project name
• ✅ Optionally removes Jest and test dependencies

Running Cleanup

pnpm clean

The script will prompt you:

1. Whether to remove Jest and testing setup
2. Whether to reinstall dependencies after cleanup

Note: You don't need to run cleanup immediately. The template works perfectly as-is, so you can test everything first.

Configuration

TypeScript

TypeScript is configured with strict mode and modern ES features. Path aliases are pre-configured:

// Instead of
import { something } from "../../lib/utils.js";

// Use
import { something } from "@/lib/utils.js";

Environment Variables

Create a .env file (or run pnpm clean to auto-generate):

# Development
NODE_ENV=development
PORT=3000

# Add your variables
API_KEY=your-api-key
DATABASE_URL=postgresql://localhost:5432/mydb

Access variables in your code:

const port = process.env.PORT || 3000;
const apiKey = process.env.API_KEY;

Jest Testing

Tests are configured to work with TypeScript out of the box:

// src/tests/math.test.ts
import { add } from "@/lib/math.js";

describe("Math utilities", () => {
  it("should add two numbers", () => {
    expect(add(2, 3)).toBe(5);
  });
});

Run tests:

# Run once
pnpm test

# Watch mode for TDD
pnpm test:watch

Common Use Cases

Building a REST API

// src/index.ts
import express from "express";

const app = express();
const port = process.env.PORT || 3000;

app.use(express.json());

app.get("/api/health", (req, res) => {
  res.json({ status: "ok" });
});

app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

Building a CLI Tool

// src/index.ts
import { Command } from "commander";

const program = new Command();

program.name("my-cli").description("My awesome CLI tool").version("1.0.0");

program
  .command("greet <name>")
  .description("Greet someone")
  .action((name) => {
    console.log(`Hello, ${name}!`);
  });

program.parse();

Tips & Tricks

Use Path Aliases

// ❌ Avoid relative imports
import { utils } from "../../../lib/utils.js";

// ✅ Use clean path aliases
import { utils } from "@/lib/utils.js";

Hot Reload During Development

The pnpm dev command uses tsx for instant hot reload. Changes are reflected immediately without restarting.

Type-Safe Environment Variables

Create a type-safe environment config:

// src/config/env.ts
interface Env {
  NODE_ENV: "development" | "production" | "test";
  PORT: number;
  API_KEY: string;
}

export const env: Env = {
  NODE_ENV: (process.env.NODE_ENV as Env["NODE_ENV"]) || "development",
  PORT: parseInt(process.env.PORT || "3000"),
  API_KEY: process.env.API_KEY || "",
};

Debugging in VS Code

Add to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug TypeScript",
      "runtimeExecutable": "pnpm",
      "runtimeArgs": ["dev"],
      "console": "integratedTerminal"
    }
  ]
}

Requirements

• Node.js 18.x or higher
• pnpm, npm, or yarn package manager

Dependencies

• typescript - TypeScript language
• tsx - TypeScript execution engine
• dotenv - Environment variable loading
• jest - Testing framework
• ts-jest - Jest TypeScript preprocessor

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Marc Tyson CLEBERT [email protected]

• Website: marctysonclebert.com
• GitHub: @clebertmarctyson
• Twitter/X: @ClebertTyson

Support the Project

If node-ts-starter has been helpful to you, consider:

• ⭐ Starring the repo
• 🐛 Reporting bugs
• 💡 Suggesting features
• 🤝 Contributing code
• ☕ Buying me a coffee

---

Made with ❤️ by Marc Tyson CLEBERT