🚀 TS-Kickstart

A no-nonsense TypeScript project scaffolder that gets you coding in seconds. Stop wasting time setting up the same boilerplate for every Node.js project.

Why?

Because setting up TypeScript + Express + MongoDB + Docker + ESLint for the 50th time is soul-crushing. This CLI does it all in one command.

Features

• 3 Project Templates: Basic backend, MongoDB API, or NPM library
• Interactive Setup: Pick only the features you need
• Proper Structure: Folders organized the way they should be
• Production Ready: Error handling, env validation, graceful shutdown built-in
• Zero Config: Everything works out of the box

Installation

npm install -g ts-kickstart

Or use it directly with npx:

npx ts-kickstart

Quick Start

# Run the CLI
ts-kickstart

# Pick your project type
# Answer a few questions
# Start coding

That's it. No joke.

Project Templates

1. Basic Backend (Express + TypeScript)

Perfect for simple APIs or microservices.

Includes:

• Express server with TypeScript
• Hot reload with nodemon
• Path aliases (@/types, @/utils)
• Basic routing setup
• Environment configuration

File Structure:

my-backend/
├── src/
│   ├── index.ts          # Main server file
│   ├── types/            # TypeScript types
│   └── ...
├── tsconfig.json
├── package.json
└── .env.example

2. MongoDB API (Express + Mongoose)

Full-featured API backend with MongoDB.

Includes:

• Everything from Basic Backend
• Mongoose with TypeScript models
• Database connection handling
• Folder structure (models, controllers, routes, middleware)
• Error handling middleware
• AsyncHandler wrapper (no try-catch spam)
• Sample CRUD routes
• Graceful shutdown

File Structure:

my-api/
├── src/
│   ├── index.ts              # Server entry
│   ├── config/
│   │   └── database.ts       # MongoDB connection
│   ├── models/
│   │   └── User.model.ts     # Sample model
│   ├── controllers/
│   │   └── user.controller.ts
│   ├── routes/
│   │   └── user.routes.ts
│   ├── middleware/
│   │   └── errorHandler.ts  # Global error handler
│   └── utils/
│       ├── asyncHandler.ts   # Async wrapper
│       └── AppError.ts       # Custom error class
├── tsconfig.json
└── .env.example

Example Controller:

export const createUser = asyncHandler(async (req: Request, res: Response) => {
  const user = await User.create(req.body);
  res.status(201).json({ success: true, data: user });
});

No try-catch needed. Errors automatically handled.

3. NPM Library

Build and publish TypeScript libraries.

Includes:

• tsup for bundling (CJS + ESM)
• TypeScript declarations
• Source maps
• Minification
• Watch mode for development

File Structure:

my-library/
├── src/
│   └── index.ts          # Library exports
├── dist/                 # Built files (auto-generated)
├── tsconfig.json
├── tsup.config.ts
└── package.json

Optional Features

When creating a project, you'll be asked about these features:

🐳 Docker Setup

Adds Docker support with MongoDB included.

What you get:

• Dockerfile for your app
• docker-compose.yml with MongoDB service
• .dockerignore
• Ready for production deployment

Usage:

docker-compose up

Your app + MongoDB running in containers. That's it.

🎨 ESLint + Prettier

Stop thinking about code formatting.

What you get:

• ESLint with TypeScript support
• Prettier integration
• Recommended rules
• Auto-fix on save (if you configure your editor)

Commands:

npm run lint          # Check for issues
npm run lint:fix      # Auto-fix issues
npm run format        # Format all files

🔐 JWT Authentication

JWT auth boilerplate (MongoDB API only).

What you get:

• JWT token generation utility
• Authentication middleware
• Protected route examples
• Environment variables for secrets

Usage:

import { authenticate } from "./middleware/auth.middleware";

router.get("/protected", authenticate, getProtectedData);

🧪 Jest Testing

Testing setup with TypeScript support.

What you get:

• Jest configured for TypeScript
• Sample test file
• Coverage reporting
• Watch mode

Commands:

npm test              # Run tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Common Workflows

Starting a MongoDB API

npx ts-kickstart

# Choose: MongoDB API
# Project name: my-awesome-api
# Docker? y
# ESLint? y
# JWT Auth? y
# Testing? y

cd my-awesome-api
docker-compose up

Now you have:

• Express + TypeScript API
• MongoDB running in Docker
• JWT authentication ready
• Linting configured
• Tests ready to write

Creating an NPM Library

npx ts-kickstart

# Choose: NPM Library
# Project name: my-cool-library
# ESLint? y
# Testing? y

cd my-cool-library
npm run dev  # Watch mode - auto rebuilds on changes

Quick Backend Without MongoDB

npx ts-kickstart

# Choose: Basic Backend
# Project name: quick-api
# Docker? n
# ESLint? y
# Testing? n

cd quick-api
npm run dev

Commands Reference

All Projects

npm run dev          # Development mode with hot reload
npm run build        # Build for production
npm run type-check   # Type check without building

MongoDB API Specific

npm start            # Start production build

Library Specific

npm run prepublishOnly  # Runs automatically before npm publish

With Linting

npm run lint         # Check code
npm run lint:fix     # Auto-fix issues
npm run format       # Format with Prettier

With Testing

npm test             # Run tests once
npm run test:watch   # Watch mode
npm run test:coverage # Coverage report

With Docker

docker-compose up              # Start services
docker-compose up -d           # Start in background
docker-compose down            # Stop services
docker-compose logs -f app     # View app logs

Environment Variables

Basic Backend

PORT=3000

MongoDB API

PORT=3000
MONGODB_URI=mongodb://localhost:27017/myapp
NODE_ENV=development

With JWT Auth

PORT=3000
MONGODB_URI=mongodb://localhost:27017/myapp
NODE_ENV=development
JWT_SECRET=your-super-secret-key-change-this
JWT_EXPIRES_IN=7d

Note: Always copy .env.example to .env and update values.

Path Aliases

All projects include TypeScript path aliases:

// Instead of:
import { User } from "../../../models/User.model";

// You can:
import { User } from "@/models/User.model";

Works in VS Code, builds, and runtime.

Project Structure Philosophy

MongoDB API Structure

src/
├── config/          # Database, environment setup
├── models/          # Mongoose models
├── controllers/     # Request handlers (business logic)
├── routes/          # Route definitions
├── middleware/      # Custom middleware (auth, validation)
└── utils/           # Helper functions, error classes

Why this structure?

• Clear separation of concerns
• Easy to find things
• Scales well as project grows
• Industry standard

Error Handling Pattern

Instead of:

app.get("/user/:id", async (req, res) => {
  try {
    const user = await User.findById(req.params.id);
    if (!user) {
      return res.status(404).json({ error: "Not found" });
    }
    res.json(user);
  } catch (error) {
    res.status(500).json({ error: "Server error" });
  }
});

We do:

export const getUserById = asyncHandler(async (req, res, next) => {
  const user = await User.findById(req.params.id);

  if (!user) {
    throw new AppError("User not found", 404);
  }

  res.json({ success: true, data: user });
});

Cleaner. Less boilerplate. Errors handled globally.

Tips & Best Practices

MongoDB Connection

The database connection auto-retries and handles graceful shutdown. Just make sure your MONGODB_URI is correct.

Development vs Production

# Development
npm run dev

# Production
npm run build
npm start

In production, use NODE_ENV=production in your .env.

Docker for Development

Docker isn't just for production. Use it in development to avoid installing MongoDB locally:

docker-compose up

Your code runs on your machine (with hot reload), but MongoDB runs in Docker.

Publishing Libraries

cd my-library
npm run build
npm publish

The prepublishOnly script ensures you always build before publishing.

Using JWT Auth

1. Generate token on login:

import { generateToken } from "@/utils/jwt";

const token = generateToken(user.id);
res.json({ token });

2. Protect routes:

import { authenticate } from "@/middleware/auth.middleware";

router.get("/profile", authenticate, getProfile);

3. Access user in controller:

export const getProfile = asyncHandler(async (req: AuthRequest, res) => {
  const userId = req.userId; // Set by authenticate middleware
  // ...
});

Troubleshooting

"Cannot find module '@/...'"

Your editor might not recognize path aliases. VS Code usually picks them up automatically from tsconfig.json. Try restarting your editor.

MongoDB connection errors

Make sure MongoDB is running:

# If using Docker
docker-compose up

# If local MongoDB
# Check if mongod is running

Port already in use

Change the PORT in your .env file:

PORT=3001

TypeScript errors on build

Run type check to see issues:

npm run type-check

Contributing

Found a bug? Want a feature? PRs welcome.

Keep it simple. Keep it useful.

License

MIT - Do whatever you want with it.

Built because I was tired of copying the same setup files between projects. Hope it saves you time too.