typerd

CLI development tools for building and running TypeScript projects with support for both TSC and SWC compilers.

Features

• Dual Compiler Support — Use TypeScript's native compiler (TSC) for full type checking, or SWC for blazing-fast compilation
• Watch Mode — Automatic recompilation and restart on file changes with intelligent debouncing
• Type Checking — Run type checking in parallel with SWC compilation for the best of both worlds
• Declaration Files — Generate .d.ts files with SWC using TSC under the hood
• Debug Support — Built-in --inspect and --inspect-brk flags with custom host:port configuration
• Path Alias Resolution — Automatic resolution of tsconfig path aliases in compiled output
• Source Maps — Inferred from your tsconfig.json or .swcrc configuration
• Crash Loop Detection — Prevents infinite restart loops when your app crashes repeatedly
• Graceful Shutdown — Proper cleanup of child processes on SIGINT/SIGTERM

Installation

pnpm add -D typerd

Global Options

| Option | Description | Default | |-----------------|-----------------------|---------| | -V, --verbose | Enable verbose output | false |

Commands

build

Build a TypeScript project.

typerd build [options]

Options:

| Option | Description | Default | |-----------------------------|---------------------------------------------|---------------| | -s, --source <dir> | Source directory | src | | -o, --output <dir> | Output directory | dist | | -c, --compiler <compiler> | Compiler to use (tsc or swc) | tsc | | --tsconfig <path> | Path to tsconfig file | auto-detected | | --clean | Clean output directory before build | true | | --no-clean | Skip cleaning output directory | | | --type-check | Run type checking (SWC only) | false | | --emit-types | Generate .d.ts declaration files (SWC only) | false | | -w, --watch | Watch mode for development | false |

start

Build and run a TypeScript project.

typerd start [entry] [options]

Arguments:

| Argument | Description | Default | |----------|-----------------------------------------|-----------| | entry | Entry file relative to source directory | main.ts |

Options:

All build options (except --emit-types) plus:

| Option | Description | Default | |----------------------------|-------------------------------------------------------------|---------| | -m, --module-type <type> | Module type for path alias resolution (esm or commonjs) | esm | | -d, --debug [hostport] | Run in debug mode (--inspect) | false | | --debug-brk [hostport] | Debug mode, pause on first line (--inspect-brk) | false |

Examples

# Build with TSC (default)
typerd build

# Build with SWC (fast, no type checking)
typerd build --compiler swc

# Build with SWC + type checking (best of both worlds)
typerd build --compiler swc --type-check

# Build with SWC + emit declaration files
typerd build --compiler swc --emit-types

# Watch mode
typerd build --watch

# Build and run once
typerd start

# Run a specific entry file
typerd start app.ts

# Watch mode with auto-restart
typerd start --watch

# Debug mode
typerd start --debug
typerd start --debug=9229
typerd start --debug-brk=localhost:9229

# CommonJS module resolution (for path aliases in watch mode)
typerd start --watch --module-type commonjs

Configuration

TypeScript (tsconfig.json)

typerd automatically detects your tsconfig.json (or tsconfig.build.json fallback). Key settings:

{
  "compilerOptions": {
    "outDir": "dist",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

• declaration/declarationMap — Used by TSC; for SWC use --emit-types flag
• sourceMap — Enables source maps for TSC builds and Node.js runtime
• paths — Automatically resolved in compiled output (non-watch mode) or at runtime (watch mode)

SWC (.swcrc)

When using SWC compiler, create a .swcrc in your project root:

{
  "$schema": "https://swc.rs/schema.json",
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "decorators": true
    },
    "target": "es2022"
  },
  "sourceMaps": true
}

• sourceMaps — Enables source maps for SWC builds and Node.js runtime

Compiler Comparison

| Feature | TSC | SWC | |-------------------|--------------|-------------------------| | Compilation Speed | Slower | ~20x faster | | Type Checking | Built-in | Via --type-check flag | | Declaration Files | Via tsconfig | Via --emit-types flag | | Source Maps | Via tsconfig | Via .swcrc | | Decorators | Full support | Full support |

Recommendation: Use SWC with --type-check for development (fast rebuilds with type safety), and TSC for production builds (most reliable).

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.x (peer dependency)

Optional Dependencies

When using SWC compiler:

pnpm add -D @swc/cli @swc/core

Troubleshooting

"Cannot find module" errors with path aliases

In watch mode, path aliases are resolved at runtime. Ensure your tsconfig.json has the correct baseUrl and paths configuration.

Crash loop detected

If your app crashes 3+ times within 5 seconds, typerd pauses restarts to prevent infinite loops. Fix the crash and save a file to trigger a restart.

SWC not found

Install SWC as a dev dependency:

pnpm add -D @swc/cli @swc/core

Type errors not showing with SWC

SWC doesn't type-check by default. Add --type-check to run TypeScript's type checker in parallel:

typerd build --compiler swc --type-check

License

MIT