Dev Tools

Purpose

@nextrush/dev provides the nextrush CLI: a dev server with hot reload, a production build command that preserves decorator metadata for DI, and code generators for controllers, services, middleware, guards, and routes. It runs on Node.js, Bun, and Deno.

Fast bundlers like esbuild and tsup strip TypeScript decorator metadata, which breaks constructor-based dependency injection (@Service, @Controller). nextrush build uses SWC specifically to preserve it. See @nextrush/di for why DI needs this metadata.

Installation

$ pnpm add @nextrush/dev

Minimal Usage

nextrush dev              # start dev server (auto-detects entry)
nextrush build            # production build to dist/
nextrush generate controller user   # scaffold a controller

API Reference

nextrush dev [entry] [options]

Starts a dev server with hot reload. Auto-detects the entry file if omitted, checking package.json (main/module), then src/index.ts, src/main.ts, src/app.ts, src/server.ts, and root-level equivalents.

On Node.js, nextrush dev uses SWC for TypeScript and decorator metadata; Bun and Deno use their native TypeScript support.

nextrush build [entry] [options]

Compiles TypeScript to dist/ with decorator metadata preserved (Node.js and Bun via SWC; Deno via npm:@swc/core, with a native-copy fallback that does not emit metadata).

nextrush generate <type> <name> (alias g)

Scaffolds a file from a template. name must match ^[a-z][a-z0-9-]*$.

Programmatic API

import { dev, build, type DevOptions, type BuildOptions } from '@nextrush/dev';
import { generate, generateCli, generateHelp, GENERATOR_TYPES, type GeneratorType } from '@nextrush/dev';
import { detectRuntime, isNode, isBun, isDeno, getRuntimeInfo, type Runtime, type RuntimeInfo } from '@nextrush/dev';
import { findEntry, getDefaultWatchPaths, loadConfig, type NextRushConfig } from '@nextrush/dev';

await dev('./src/index.ts', { port: 8080 });
await build('./src/index.ts', { outDir: 'dist', minify: true });
await generate('controller', 'user');       // writes the file, returns its path
await generateCli(['controller', 'user']);  // parses CLI args and calls generate()
generateHelp();                             // prints generator usage to stdout

generate(type, name, cwd?) validates the name, writes the templated file, and returns the output path — this is what nextrush generate calls internally. generateCli(args) is the CLI entry point (arg parsing, validation, error reporting) and generateHelp() prints the usage text shown by nextrush generate --help.

DevOptions and BuildOptions accept the same fields as the CLI flags above (port, watch, inspect, inspectPort for dev; outDir, target, sourcemap, minify, decoratorMetadata, clean for build).

Configuration

Decorator-based projects require both flags in tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

nextrush dev warns at startup if only one flag is set. Projects without decorators can omit both.

One Practical Example

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

pnpm dev      # hot-reload dev server on :8080
pnpm build    # dist/ with decorator metadata + minification
pnpm start    # run the build

See Also

• nextrush — Meta package
• @nextrush/class — Controllers and registration
• @nextrush/di — Dependency injection