@yigityalim/next-router-cli

🎨 Beautiful CLI tool for @yigityalim/next-router - route management, validation, and OpenAPI generation.

Features

✨ Beautiful Design - Enhanced UI with colors, boxes, and emojis
🚀 Static Analysis - No need to run your application
📊 Multiple Formats - JSON, YAML, CSV, and beautiful tables
🔍 Smart Validation - Detailed error and warning reports
⚡ Fast - TypeScript AST parsing with zero runtime overhead

Installation

pnpm add -D @yigityalim/next-router-cli

Usage

Generate OpenAPI Specification

# JSON format (default)
route-handler generate openapi --output ./openapi.json

# YAML format
route-handler generate openapi --output ./openapi.yaml --format yaml

# With custom title and version
route-handler generate openapi \
  --output ./docs/api.yaml \
  --format yaml \
  --title "My API" \
  --version "2.0.0"

Output:

┌───────────────────────────────────┐
│ 🚀 Generate OpenAPI Specification │
└───────────────────────────────────┘

▸ Scanning
ℹ Discovering route files...
✓ Found 16 route files

▸ Parsing
ℹ Extracting route metadata...
✓ Parsed 38 routes

▸ Generating
ℹ Creating OpenAPI 3.1 spec (yaml)...
✓ OpenAPI spec written to: api-spec.yaml

┌─✨ Generation Complete────┐
│ Format:    YAML            │
│ Output:    api-spec.yaml   │
│ Routes:    38              │
│ Paths:     13              │
└───────────────────────────┘

List All Routes

# Beautiful table (default)
route-handler list

# JSON format
route-handler list --format json

# CSV format
route-handler list --format csv

# Filter by pattern
route-handler list --filter "/api/users/*"

Output:

┌────────────────────┐
│ 📋 List API Routes │
└────────────────────┘

┌─────────┬──────────────────┬──────────┬────────────┐
│ Method  │ Path             │ Auth     │ Rate Limit │
├─────────┼──────────────────┼──────────┼────────────┤
│ GET     │ /api/users       │ Required │ 100/min    │
│ POST    │ /api/users       │ Required │ 10/min     │
│ GET     │ /api/users/[id]  │ Required │ 100/min    │
│ DELETE  │ /api/users/[id]  │ Admin    │ 50/min     │
└─────────┴──────────────────┴──────────┴────────────┘

✓ Total: 4 routes

Validate Routes

# Standard validation
route-handler validate

# Strict mode (more checks)
route-handler validate --strict

# Verbose output
route-handler validate --verbose

Output:

┌────────────────────────┐
│ 🔍 Validate API Routes │
└────────────────────────┘

▸ Scanning
ℹ Discovering route files...
✓ Found 16 route files

▸ Analyzing
ℹ Extracting and validating metadata...

┌─📊 Validation Results─┐
│ Routes:    38           │
│ Errors:    0            │
│ Warnings:  12           │
└────────────────────────┘

▸ Warnings
⚠   POST /api/users - Missing OpenAPI summary
⚠   POST /api/users - Missing OpenAPI tags
⚠   DELETE /api/users/[id] - Missing body schema
⚠   ... and 9 more warnings

Development Mode

route-handler dev

Coming soon - watch mode with auto-validation

Options

Global Options

• --cwd <path> - Working directory (default: current directory)
• --verbose - Enable verbose logging

Generate Options

• -o, --output <path> - Output file path
• -f, --format <format> - Output format: json or yaml
• -t, --title <title> - API title
• -v, --version <version> - API version
• -s, --servers <urls...> - Server URLs

List Options

• -f, --format <format> - Output format: table, json, or csv
• --filter <pattern> - Filter routes by glob pattern

Validate Options

• --strict - Enable strict validation mode

How It Works

1. Scans your Next.js App Router structure for route files
2. Parses TypeScript AST to extract RouteBuilder metadata
3. Extracts .openapi(), .schemas(), .auth(), etc.
4. Generates OpenAPI 3.1 spec or validates routes
5. No runtime - pure static analysis!

Examples

Generate OpenAPI for Production

route-handler generate openapi \
  --output ./public/api-docs.json \
  --title "Production API" \
  --version "1.0.0" \
  --servers https://api.example.com

Export Routes to CSV

route-handler list --format csv > routes.csv

Validate Before Deploy

route-handler validate --strict || exit 1

Requirements

• Next.js 14+ with App Router
• @yigityalim/next-router package
• TypeScript

Documentation

For full documentation about the route-handler library, visit ../core/ROADMAP.md.

License

MIT