dev

Development mode with automatic schema and OpenAPI regeneration. File watching, Ink TUI, and integrated dev server — code and your types stay in sync.

`igniter dev`

The dev command starts a development environment that watches your router and features for changes, then automatically regenerates the client schema and OpenAPI specification. It also starts your development server and displays a split-pane terminal UI.

igniter dev [options]

Options

Option	Type	Default	Description
`--router`	`string`	`src/igniter.router.ts`	Path to the router file to watch
`--output`	`string`	`src/igniter.schema.ts`	Output path for the client schema file
`--docs-output`	`string`	`./src/docs`	Output directory for the OpenAPI spec
`--cmd`	`string`	auto-detected	Custom command to start the development server

How It Works

Startup

On launch, the CLI:

Detects the package manager from npm_config_user_agent
Resolves paths — router, schema output, docs output — relative to the project root
Validates that the router file exists (exits with error if not found)
Generates initial output — runs schema generation, then docs generation
Starts the dev server using the --cmd flag or auto-detected default

File Watching

The CLI watches for changes using chokidar with a 300ms debounce:

src/igniter.router.ts — the main router file
src/features/ — all feature directories (recursive)

Ignored patterns:

node_modules/
.git/
dist/
.next/
.turbo/
.cache/
*.test.ts / *.spec.ts

Auto-Regeneration

When a watched file changes:

The debounce timer resets (300ms)
After the debounce period, the CLI regenerates:
- Client schema (igniter.schema.ts) — extracted from the router
- OpenAPI docs (src/docs/) — generated from the router
Results are logged to the TUI with timing and metadata

# Example TUI output after regeneration:
# ✅ Schema regenerated in 0.86s (12 controllers, 47 actions)
# ✅ OpenAPI docs regenerated in 0.42s (23.4 KB)

Dev Server Integration

If --cmd is provided (or auto-detected), the CLI spawns the dev server as a child process:

# Explicit command
igniter dev --cmd "pnpm dev"

# Auto-detected defaults:
# npm  → "npm run dev"
# pnpm → "pnpm dev"
# yarn → "yarn dev"
# bun  → "bun dev"

The dev server's stdout and stderr are captured and displayed in the App Logs panel of the TUI.

The dev server is started with NODE_ENV=development and runs in the project's working directory. If it exits with a non-zero code, a warning is logged to the TUI.

Terminal UI (TUI)

The dev command renders a split-pane terminal UI using Ink (React for the terminal):

┌──────────────────────────────────────────────────────┐
│  Igniter Dev Mode                        [q] to quit  │
├──────────────────────┬───────────────────────────────┤
│   Igniter Logs       │       App Logs                 │
│                      │                                │
│  ✅ Schema regenera… │  > next dev                    │
│  ✅ OpenAPI docs re… │  ▲ Ready in 2.1s               │
│  ℹ File changed: …   │  ▲ Local: http://localhost:3000│
│  ✅ Schema regenera… │  GET /api/users 200 (45ms)     │
│                      │  POST /api/auth 201 (12ms)     │
│                      │                                │
└──────────────────────┴───────────────────────────────┘

Igniter Logs (left panel): Schema regeneration, doc generation, file change events, errors
App Logs (right panel): Your dev server output — Next.js, Express, etc.
Exit: Press q or send SIGINT (Ctrl+C)

Logs are capped at 1,000 entries per panel to prevent memory growth.

Graceful Shutdown

The CLI registers cleanup handlers for SIGINT and SIGTERM:

Clears any pending debounce timeout
Closes the chokidar file watcher
Sends SIGTERM to the dev server process
Unmounts the Ink TUI
Exits with code 0

Examples

Standard Next.js Dev Mode

cd my-nextjs-app
igniter dev --cmd "pnpm dev"

Express API Dev Mode

cd my-express-api
igniter dev --cmd "pnpm dev"

Custom Router and Output Paths

igniter dev \
  --router ./src/custom/igniter.router.ts \
  --output ./src/generated/igniter.schema.ts \
  --docs-output ./public/openapi \
  --cmd "pnpm dev"

Without a Dev Server (Watch Only)

# If --cmd is omitted and there's no dev script, the CLI
# runs in watch-only mode — regenerating on file changes
# without a dev server.
igniter dev

`generate schema` (Watch Mode)

The generate schema command has a programmatic watch mode variant used internally by igniter dev. It bundles the router using esbuild in-memory and extracts the schema without writing files to disk:

Router file → esbuild bundle → Router introspection → Schema type extraction → Write output

Returns: { controllers: number, actions: number, durationMs: number }

`generate docs` (Watch Mode)

Similarly, generate docs has a watch-mode variant that produces OpenAPI output and returns metadata:

Router file → esbuild bundle → Router introspection → OpenAPI conversion → Write spec

Returns: { sizeKb: number, durationMs: number }

dev