type-safe-router-gen

Type-Safe Router Generator

A comprehensive CLI tool for generating type-safe navigation helpers in modern web frameworks. Generate type-safe route helpers, catch routing errors at compile time, analyze route performance, and audit your routing architecture with full IDE autocompletion support.

npm install type-safe-router-gen
npx router-gen generate --analytics --generate-api

🆕 NEW in v0.3.0: Complete Route Management Suite

✅ Route Validation - Detect broken route references across your codebase
✅ Health Checks - Comprehensive route analysis and recommendations
✅ Documentation Generator - Auto-generate beautiful route documentation
✅ Migration Assistant - Seamlessly migrate between routing frameworks
✅ Route Analytics - Performance analysis and usage insights
✅ Professional CLI - Enterprise-ready tooling with detailed reporting

Previous: Next.js App Router support, Route Analytics, API helpers, Performance analysis, and Route auditing.

Quick Start

1. Install the Package

# Install globally
npm install -g type-safe-router-gen

# Or use npx (recommended)
npx router-gen --help

2. Generate Routes

# Generate routes from your pages directory
npx router-gen generate --input ./pages --output ./src/routes.ts

# Or use the default paths (looks for pages/ or app/ directories)
npx router-gen generate

3. Use Generated Routes

import { Routes } from './src/routes';

// Type-safe navigation
const blogUrl = Routes.blog.slug({ slug: 'my-post' });        // "/blog/my-post"
const searchUrl = Routes.search({ q: 'typescript', page: 2 }); // "/search?q=typescript&page=2"

// TypeScript catches errors at compile time
Routes.blog.slug();                    // Error: missing required 'slug'
Routes.blog.slug({ id: 123 });         // Error: 'id' is not assignable to 'slug'
Routes.search({ invalid: 'param' });   // Error: 'invalid' is not a valid query param

Supported File Structures

Next.js (App Router & Pages Router)

# Pages Router
pages/
├── index.tsx              → Routes.home()
├── about.tsx              → Routes.about()
├── blog/
│   ├── [slug].tsx         → Routes.blog.slug({ slug: string })
│   └── index.tsx          → Routes.blog.index()
└── docs/
    └── [[...slug]].tsx    → Routes.docs.slug({ slug?: string[] })

# App Router (NEW)
app/
├── page.tsx               → Routes.home()
├── about/
│   └── page.tsx           → Routes.about()
├── blog/
│   ├── [slug]/
│   │   └── page.tsx       → Routes.blog.slug({ slug: string })
│   └── page.tsx           → Routes.blog.index()
└── (dashboard)/           # Route groups supported
    └── analytics/
        └── page.tsx       → Routes.analytics()

Remix

app/routes/
├── _index.tsx             → Routes.home()
├── about.tsx              → Routes.about()
├── blog.$slug.tsx         → Routes.blog.slug({ slug: string })
└── docs.$.tsx             → Routes.docs.catchAll({ '*': string })

Astro & SvelteKit

src/pages/                 # Astro
src/routes/                # SvelteKit
├── index.astro            → Routes.home()
├── about.astro            → Routes.about()
├── blog/
│   └── [slug].astro       → Routes.blog.slug({ slug: string })

CLI Commands

Generate Routes

# Basic generation
npx router-gen generate

# With custom paths and Next.js App Router
npx router-gen generate --input ./app --framework nextjs-app

# Generate with analytics and API helpers
npx router-gen generate --analytics --generate-api --generate-tests

# For different frameworks
npx router-gen generate --framework remix
npx router-gen generate --framework astro
npx router-gen generate --framework sveltekit

Route Analytics & Performance

# Analyze route usage and generate insights
npx router-gen audit --source ./src

# Performance analysis for route optimization  
npx router-gen performance

# Watch mode with analytics
npx router-gen watch --analytics --generate-api

Watch Mode (Auto-regenerate)

# Watch for file changes and auto-regenerate
npx router-gen watch

# Watch with all features enabled
npx router-gen watch --analytics --generate-api --generate-tests

Route Auditing

# Find unused routes and potential issues
npx router-gen audit

# Audit with custom source directory
npx router-gen audit --source ./components --input ./pages

# Auto-fix mode (experimental)
npx router-gen audit --fix

🆕 Route Validation & Health

# Validate all route usages across your codebase
npx router-gen validate --input ./pages --source ./src --strict

# Comprehensive health check (combines all analysis tools)
npx router-gen health --input ./pages

🆕 Documentation & Migration

# Generate beautiful route documentation
npx router-gen docs --input ./pages --output ./ROUTES.md

# Migrate from Pages Router to App Router
npx router-gen migrate --pages-dir ./pages --app-dir ./app

Initialize Configuration

# Create a router-gen.config.json file
npx router-gen init

Configuration

Create a router-gen.config.json file in your project root:

{
  "input": "./pages",
  "output": "./src/generated-routes.ts",
  "framework": "nextjs",
  "excludePatterns": ["**/api/**", "**/_*"],
  "includeQueryParams": true,
  "generateTests": false
}

Configuration Options

Option	Type	Default	Description
input	string	"./pages"	Directory containing your route files
output	string	"./src/generated-routes.ts"	Output file for generated routes
framework	string	"nextjs"	Framework type (nextjs, nextjs-app, remix, astro, sveltekit)
excludePatterns	string[]	["**/api/**", "**/_*"]	Glob patterns to exclude
includeQueryParams	boolean	true	Extract query parameters from route files
generateTests	boolean	false	Generate test files alongside routes
generateApiRoutes	boolean	false	Generate API route helpers with fetch utilities
routeAnalytics	boolean	false	Generate route analytics and usage reports

Query Parameters

Define query parameters in your route files using a QueryParams interface:

// pages/search.tsx
export interface QueryParams {
  q: string;              // Required query param
  page?: number;          // Optional query param  
  category?: string[];    // Optional array query param
}

export default function SearchPage() {
  return <div>Search Page</div>;
}

Generated route:

Routes.search({ 
  q: 'typescript',           // Required
  page: 2,                   // Optional
  category: ['tutorial']     // Optional array
}); 
// → "/search?q=typescript&page=2&category=tutorial"

Advanced Features

Route Analytics

Get comprehensive insights about your routing architecture:

npx router-gen generate --analytics

Generates route-analytics.json with:

• Total route count and distribution
• Dynamic vs static route analysis
• Route depth and complexity metrics
• Parameter usage patterns
• Performance recommendations

{
  "totalRoutes": 47,
  "dynamicRoutes": 12,
  "staticRoutes": 35,
  "nestedRoutes": 23,
  "routeDepthDistribution": { "1": 15, "2": 20, "3": 12 },
  "parameterUsage": { "id": 8, "slug": 5, "category": 3 }
}

Route Auditing

Find unused routes, potential issues, and optimization opportunities:

npx router-gen audit

What it detects:

• Unused routes that can be removed
• Magic string usage (potential broken links)
• Route usage patterns across your codebase
• Most and least used routes

Sample output:

Route Usage Report:
   Total Routes: 47
   Used Routes: 42
   Unused Routes: 5
   Potential Issues: 3

Unused Routes:
   /admin/legacy -> pages/admin/legacy.tsx
   /temp/debug -> pages/temp/debug.tsx

Potential Issues:
   Potential broken link in src/components/Nav.tsx: "/old-path"

Performance Analysis

Analyze route performance and get optimization suggestions:

npx router-gen performance

Analyzes:

• File size and bundle impact
• Code complexity metrics
• Dependency analysis
• Performance anti-patterns

Sample output:

Performance Analysis Results:
   Total Routes: 47
   Total Size: 892.3 KB
   Average Complexity: 6.2
   Routes with Issues: 8

Routes Needing Attention:
   pages/dashboard/analytics.tsx
     Size: 45.2 KB, Complexity: 15, Lines: 387
     • Large file size - consider code splitting
     • High complexity - consider refactoring

API Route Helpers

Generate type-safe API helpers with built-in fetch utilities:

npx router-gen generate --generate-api

For API routes like:

pages/api/
├── users/
│   ├── [id].ts           # GET /api/users/:id
│   └── index.ts          # GET /api/users
└── posts/
    └── [slug].ts         # GET /api/posts/:slug

Generates generated-routes-api.ts:

export const ApiRoutes = {
  users: {
    index: () => '/api/users',
    id: (params: { id: string }) => `/api/users/${params.id}`
  },
  posts: {
    slug: (params: { slug: string }) => `/api/posts/${params.slug}`
  }
};

// Type-safe fetch helpers
export const api = {
  get: async <T>(url: string, options?: RequestInit): Promise<T> => { /* ... */ },
  post: async <T>(url: string, data?: any, options?: RequestInit): Promise<T> => { /* ... */ },
  // ... put, delete
};

// Usage
const user = await api.get<User>(ApiRoutes.users.id({ id: '123' }));
const users = await api.post<User[]>(ApiRoutes.users.index(), { name: 'John' });

Real-World Examples

Next.js E-commerce Site

pages/
├── index.tsx                    → Routes.home()
├── products/
│   ├── index.tsx               → Routes.products.index()
│   ├── [id].tsx                → Routes.products.id({ id: string })
│   └── category/
│       └── [slug].tsx          → Routes.products.category.slug({ slug: string })
├── user/
│   ├── profile.tsx             → Routes.user.profile()
│   └── orders/
│       ├── index.tsx           → Routes.user.orders.index()
│       └── [orderId].tsx       → Routes.user.orders.orderId({ orderId: string })
└── search.tsx                  → Routes.search({ q: string, filters?: string[] })

Usage in components:

import { Routes } from '../generated-routes';
import Link from 'next/link';

function ProductCard({ product }) {
  return (
    <Link href={Routes.products.id({ id: product.id })}>
      {product.name}
    </Link>
  );
}

function SearchForm() {
  const handleSearch = (query: string) => {
    router.push(Routes.search({ q: query }));
  };
}

Remix Blog

app/routes/
├── _index.tsx                  → Routes.home()
├── blog._index.tsx             → Routes.blog.index()
├── blog.$slug.tsx              → Routes.blog.slug({ slug: string })
├── blog.admin.tsx              → Routes.blog.admin()
└── blog.admin.new.tsx          → Routes.blog.admin.new()

Integration with Popular Tools

React Router / Remix

import { useNavigate } from '@remix-run/react';
import { Routes } from '~/generated-routes';

function MyComponent() {
  const navigate = useNavigate();
  
  const goToBlog = (slug: string) => {
    navigate(Routes.blog.slug({ slug }));
  };
}

Next.js Router

import { useRouter } from 'next/router';
import { Routes } from '../generated-routes';

function MyComponent() {
  const router = useRouter();
  
  const goToProduct = (id: string) => {
    router.push(Routes.products.id({ id }));
  };
}

Astro

---
import { Routes } from '../generated-routes';
const blogUrl = Routes.blog.slug({ slug: 'my-post' });
---

<a href={blogUrl}>Read my blog post</a>

Development Workflow

1. Setup Development Mode

# Terminal 1: Watch for route changes
npx router-gen watch

# Terminal 2: Run your dev server
npm run dev

2. Add New Routes

• Create a new route file (e.g., pages/blog/[slug].tsx)
• Routes are automatically regenerated
• Import and use the new route: Routes.blog.slug({ slug: 'new-post' })

3. Refactoring Routes

When you rename or move route files:

• Routes are automatically regenerated
• TypeScript will show errors where old routes are used
• Update your code using IDE autocompletion

Best Practices

1. Consistent Query Parameters

// Good: Consistent interface across similar routes
export interface SearchParams {
  q: string;
  page?: number;
  sort?: 'asc' | 'desc';
}

2. Descriptive Route Names

// Good: Clear hierarchy
pages/
├── dashboard/
│   ├── analytics/
│   │   └── [timeframe].tsx    → Routes.dashboard.analytics.timeframe()
│   └── settings/
│       └── profile.tsx        → Routes.dashboard.settings.profile()

// Avoid: Flat structure
pages/
├── dashboard-analytics-timeframe.tsx
└── dashboard-settings-profile.tsx

3. Type-Safe Redirects

// Good: Type-safe redirects
const redirectToLogin = () => {
  return Response.redirect(Routes.auth.login());
};

// Avoid: Magic strings
const redirectToLogin = () => {
  return Response.redirect('/auth/login');
};

Advanced Configuration

Custom Route Transformations

{
  "input": "./pages",
  "output": "./src/routes.ts",
  "framework": "nextjs",
  "excludePatterns": [
    "**/api/**",
    "**/_*",
    "**/components/**"
  ],
  "includeQueryParams": true,
  "generateTests": true
}

Multiple Output Files

Generate routes for different parts of your app:

# Admin routes
npx router-gen generate --input ./pages/admin --output ./src/admin-routes.ts

# Public routes  
npx router-gen generate --input ./pages/public --output ./src/public-routes.ts

Installation for Different Package Managers

npm

npm install type-safe-router-gen
npx router-gen generate

yarn

yarn add type-safe-router-gen
yarn router-gen generate

pnpm

pnpm add type-safe-router-gen
pnpm router-gen generate

bun

bun add type-safe-router-gen
bunx router-gen generate

Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by the type-safety patterns in modern web frameworks
• Built for the developer community who values type safety and great DX
• Special thanks to all contributors and users providing feedback

Built with care for the TypeScript community