tsc-app

A fast, interactive TypeScript project generator for Node.js. Create production-ready TypeScript projects with a single command.

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   npx tsc-app my-awesome-project                            │
│                                                             │
│   ✓ TypeScript 5.7 with strict mode                         │
│   ✓ ESLint + Prettier configured                            │
│   ✓ Modern ES2022 target                                    │
│   ✓ Fast development with tsx                               │
│   ✓ Ready in seconds!                                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Quick Start

Option 1: Interactive Mode (Recommended for Beginners)

npx tsc-app my-project

You'll see prompts like this:

  tsc-app - TypeScript Project Generator

? Project name: my-project
? Module system: › ESM (ES Modules)
? Enable TypeScript strict mode? › Yes
? ECMAScript target: › ES2022 (Recommended)
? Source directory: › src
? Output directory: › dist
...

Option 2: Quick Setup with Defaults

Skip all prompts and use sensible defaults:

npx tsc-app my-project -y

Option 3: Customize with Flags

npx tsc-app my-project --testing --test-runner vitest --build-tool tsup

What Gets Generated?

When you run tsc-app, it creates a complete project structure:

my-project/
├── src/
│   └── index.ts          # Your main TypeScript file
├── dist/                  # Compiled JavaScript (after build)
├── package.json           # Project dependencies & scripts
├── tsconfig.json          # TypeScript configuration
├── eslint.config.js       # ESLint rules (if enabled)
├── .prettierrc            # Prettier formatting (if enabled)
├── .gitignore             # Git ignore patterns
├── .editorconfig          # Editor settings
├── .nvmrc                 # Node version (22)
└── README.md              # Project documentation

Step-by-Step Guide

1. Create Your Project

npx tsc-app hello-typescript

2. Navigate to Project

cd hello-typescript

3. Start Development

npm run dev

You'll see:

Hello, World!

4. Make Changes

Edit src/index.ts:

function greet(name: string): string {
  return `Hello, ${name}!`;
}

console.log(greet('TypeScript'));  // Output: Hello, TypeScript!

The dev server auto-reloads when you save!

5. Build for Production

npm run build

6. Run Production Build

npm start

Available Scripts

| Script | Command | Description | |--------|---------|-------------| | dev | npm run dev | Start development with hot reload | | build | npm run build | Compile TypeScript to JavaScript | | start | npm start | Run the compiled code | | typecheck | npm run typecheck | Check types without building | | lint | npm run lint | Find code issues with ESLint | | lint:fix | npm run lint:fix | Auto-fix ESLint issues | | format | npm run format | Format code with Prettier | | test | npm test | Run tests (if testing enabled) |

Configuration Options

Interactive Prompts

When you run tsc-app without -y, you'll be asked about:

| Option | Choices | Default | |--------|---------|---------| | Module System | ESM, CommonJS | ESM | | Strict Mode | Yes, No | Yes | | ES Target | ES2020, ES2021, ES2022, ESNext | ES2022 | | Source Dir | Any folder name | src | | Output Dir | Any folder name | dist | | Declaration Files | Yes, No | Yes | | Incremental Build | Yes, No | No | | Path Aliases | Yes, No | No | | ESLint | Yes, No | Yes | | ESLint Config | Recommended, Strict | Recommended | | Prettier | Yes, No | Yes | | Testing | Yes, No | No | | Test Runner | Vitest, Jest, Node | Vitest | | Build Tool | tsc, tsup, esbuild | tsc | | Dev Runner | tsx, ts-node, nodemon | tsx | | Package Manager | npm, pnpm, yarn | npm | | Initialize Git | Yes, No | Yes | | Install Dependencies | Yes, No | Yes |

Command Line Flags

# Basic usage
npx tsc-app <project-name> [options]

# Examples
npx tsc-app my-api -y                          # Use all defaults
npx tsc-app my-api --testing                   # Add testing
npx tsc-app my-api --build-tool tsup           # Use tsup bundler
npx tsc-app my-api -p pnpm                     # Use pnpm
npx tsc-app my-api --no-eslint --no-prettier   # Skip linting

All available flags:

-V, --version               Show version
-m, --module <type>         esm | commonjs (default: esm)
--strict / --no-strict      TypeScript strict mode (default: true)
-t, --target <target>       ES2020 | ES2021 | ES2022 | ESNext
--src-dir <dir>             Source directory (default: src)
--out-dir <dir>             Output directory (default: dist)
-d, --declaration           Generate .d.ts files (default: true)
-i, --incremental           Enable incremental builds
--aliases                   Enable path aliases (@/*)
--eslint / --no-eslint      Add ESLint (default: true)
--eslint-config <type>      recommended | strict
--prettier / --no-prettier  Add Prettier (default: true)
--testing                   Add testing framework
--test-runner <runner>      vitest | jest | node
-b, --build-tool <tool>     tsc | tsup | esbuild
--dev-runner <runner>       tsx | ts-node | nodemon
--git / --no-git            Initialize git (default: true)
--install / --no-install    Install dependencies (default: true)
-p, --package-manager <pm>  npm | pnpm | yarn
-y, --yes                   Skip prompts, use defaults
-h, --help                  Show help

Common Recipes

API Server Project

npx tsc-app my-api --testing --test-runner vitest

CLI Tool

npx tsc-app my-cli --build-tool tsup

Library/Package

npx tsc-app my-lib --declaration --build-tool tsup

Fast Development Setup

npx tsc-app my-project --dev-runner tsx

Minimal Setup

npx tsc-app my-project --no-eslint --no-prettier --no-git -y

Understanding the Configuration

TypeScript Strict Mode

When enabled (default), TypeScript catches more errors:

// With strict mode ON - Error! ✓
function greet(name: string) {
  console.log(name.toUppercase());  // Error: 'toUppercase' doesn't exist
}

// Without strict mode - No error, crashes at runtime ✗

ESM vs CommonJS

| Feature | ESM (Modern) | CommonJS (Legacy) | |---------|--------------|-------------------| | Import syntax | import x from 'y' | const x = require('y') | | Export syntax | export { x } | module.exports = x | | Top-level await | ✓ Yes | ✗ No | | Tree shaking | ✓ Yes | ✗ Limited | | Recommendation | Use this | For older projects |

Build Tools Comparison

| Tool | Speed | Features | Best For | |------|-------|----------|----------| | tsc | Slow | Type checking | Learning, simple projects | | tsup | Fast | Bundling, tree-shaking | Libraries, CLI tools | | esbuild | Fastest | Basic bundling | Speed-critical builds |

Dev Runners Comparison

| Runner | Speed | ESM Support | Best For | |--------|-------|-------------|----------| | tsx | Fast | ✓ Native | Modern projects | | ts-node | Medium | ✓ Via loader | Compatibility | | nodemon | Slow | Via ts-node | File watching |

Troubleshooting

"Directory already exists"

# Remove existing folder or choose a different name
rm -rf my-project
npx tsc-app my-project

"Module not found" errors

# Make sure dependencies are installed
cd my-project
npm install

ESLint errors after generation

# Run auto-fix
npm run lint:fix

TypeScript errors

# Check what's wrong
npm run typecheck

Requirements

• Node.js: 22.0.0 or higher
• npm/pnpm/yarn: Any recent version

Check your Node version:

node --version  # Should show v22.x.x or higher

License

MIT

Contributing

Issues and PRs welcome at github.com/tamil202/ts-app