next-routes-kit

A comprehensive toolkit for Next.js routing - providing route constants generation and type-safe routing utilities.

Features

🚀 Route Constants Generator - Automatically generate type-safe route constants from your App Directory
🔧 Type-Safe Utilities - Build dynamic routes with full TypeScript support
📁 Monorepo Support - Works seamlessly with monorepo structures
⚡ CLI & Configuration - Flexible setup via CLI options or config files

Installation

npm install next-routes-kit
# or
yarn add next-routes-kit

Quick Start

1. Configure Routes

Create route.json files in your page directories:

// src/app/dashboard/route.json
{
  "name": "Dashboard",
}
// src/app/users/[id]/route.json
{
  "groupName": "User",
  "name": "Detail"
}

2. Generate Route Constants

yarn generate-route-constants

3. Use Generated Constants

import { ROUTES } from './lib/routes';
import { buildRoute } from 'next-routes-kit';

// Static routes
<Link href={ROUTES.Dashboard}>Dashboard</Link>

// Dynamic routes with type safety
const userPath = buildRoute(ROUTES.User.Detail, { id: '123' });
<Link href={userPath}>User Profile</Link>

API

1. generate-route-constants

# Basic usage
yarn generate-route-constants

# With options
yarn generate-route-constants --output ./src/constants --name routes.ts --constant-name AppRoute

# Short options
yarn generate-route-constants -o ./src/constants -n routes.ts

CLI Options

• -o, --output <path>: Output directory (default: ./src/constants)
• -n, --name <filename>: Output filename (default: routes.ts)
• -i, --input <path>: App directory path (default: ./src/app)
• --constant-name <name>: Constant name for routes object (default: ROUTES)
• -c, --config <path>: Configuration file path (optional)

Configuration File (Optional)

Create a route-constants.config.js file in your project root:

module.exports = {
  outputDir: './src/constants',  // Output directory
  filename: 'routes.ts',         // Filename
  inputDir: './src/app',         // App directory path
  constantName: 'ROUTES'         // Constant name for routes object
};

Usage

⚠️ Important: route.json Required Only pages with route.json files will be generated as route constants.

route.json Configuration Create a route.json file in each page directory to configure routes:

{
  "name": "Dashboard",           // Required: Route name
  "groupName": "Admin"          // Optional: Group name for grouping
}

🔄 Inheritance Feature Child directories automatically inherit groupName from parent directories.

posts/route.json → { "name": "Posts", "groupName": "Posts" }
├── [id]/route.json → { "name": "Detail" }  // Inherits "Posts"
│   └── edit/route.json → { "name": "Edit" }  // Inherits "Posts"

Inheritance Priority:

1. Own groupName (highest priority)
2. Nearest parent's groupName
3. No grouping

Example

src/app/
├── about/
│   ├── page.tsx
│   └── route.json            → { "name": "About" }
├── posts/
│   ├── page.tsx
│   ├── route.json            → { "name": "List", "groupName": "Posts" }
│   ├── [id]/
│   │   ├── page.tsx
│   │   ├── route.json        → { "name": "Detail" } // Inherits "Posts"
│   │   └── edit/
│   │       ├── page.tsx
│   │       └── route.json    → { "name": "Edit" } // Inherits "Posts"

Result:
{
  "About": "/about",
  "Posts": {
    "List": "/posts",
    "Detail": "/posts/[id]",
    "Edit": "/posts/[id]/edit"
  }
}

2. Type-Safe Routing Utilities

The package provides powerful utilities for type-safe dynamic route handling:

import { ROUTES } from './constants/routes';
import { buildRoute, type PathParams } from 'next-routes-kit';

// Type-safe path generation for dynamic routes
const postPath = buildRoute(ROUTES.Posts.Detail, { id: '123' });
// Result: '/posts/123'

// Type checking for parameters
type PostParams = PathParams<typeof ROUTES.Posts.Detail>;
// Type: { id: string }

// Usage in components
function PostLink({ postId }: { postId: string }) {
  const href = buildRoute(ROUTES.Posts.Detail, { id: postId });
  return <Link href={href}>View Post</Link>;
}