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