Dev Tools

Modern bundlers like esbuild and tsx strip decorator metadata that dependency injection needs. The @nextrush/dev CLI provides a hot-reloading dev server and a production build pipeline that preserves this metadata using SWC.

What You Will Build

A development workflow with a hot-reloading dev server and a production build that compiles TypeScript with SWC, preserving decorator metadata for DI.

Prerequisites

• Node.js 22+, Bun, or Deno installed
• An existing NextRush project (or a src/index.ts entry file)
• tsconfig.json — for class-based code (nextrush/class, DI), enable experimentalDecorators and emitDecoratorMetadata (the class-based / full scaffolds do this automatically). Functional scaffolds omit them on purpose because route handlers do not use decorators.

Installation

$ pnpm add -D @nextrush/dev

Step-by-Step Setup

{
  "scripts": {
    "dev": "nextrush dev",
    "build": "nextrush build",
    "start": "node dist/index.js"
  }
}

npx nextrush dev

npx nextrush build

Dev Server Options

npx nextrush dev ./src/app.ts --port 4000 --inspect

The port also respects the PORT environment variable when --port is not set.

Build Options

npx nextrush build --outDir dist --minify --target es2022

Runtime Behavior

The CLI detects your runtime and adapts automatically:

Entry File Detection

The CLI finds your entry file in this order:

1. package.json main or module field (converts dist/ paths to src/)
2. src/index.ts, src/main.ts, src/app.ts, src/server.ts
3. index.ts, main.ts, app.ts, server.ts

Override by passing the entry directly: npx nextrush dev ./src/app.ts

Configuration File

The CLI loads settings from nextrush.config.ts or a "nextrush" field in package.json:

export default {
  dev: {
    port: 4000,
    watch: ['src', 'config'],
  },
  build: {
    outDir: 'dist',
    target: 'es2022',
    minify: false,
  },
};

CLI flags override config file values.

Verification

Run the dev server and confirm the output:

npx nextrush dev

You should see:

⚡ NextRush Dev Server

  Runtime:  node v22.x.x
  Entry:    src/index.ts
  Port:     3000
  Watching: src

Programmatic API

For build scripts, monorepo setups, or test harnesses:

import { dev, build, detectRuntime } from '@nextrush/dev';

// Dev server
await dev('./src/app.ts', { port: 4000, inspect: true });

// Production build
await build('./src/index.ts', { outDir: 'dist', minify: true });

// Runtime detection
const runtime = detectRuntime(); // 'node' | 'bun' | 'deno'

Next Steps