next-routes-kit/readme.md

utility modules for Next.js Next.js App Directory

# 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

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

## Quick Start

### 1. Configure Routes

Create `route.json` files in your page directories:

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

### 2. Generate Route Constants

```bash
yarn generate-route-constants
```

### 3. Use Generated Constants

```typescript
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

```bash
# 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:

```javascript
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:
```json
{
  "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:

```typescript
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>;
}
```