generate-next-route-constants/readme.md

Generate route constants for Next.js App Directory

# Next.js Route Constants Generator

A package that automatically scans Next.js App Directory routes and generates type-safe route constants.

## Installation

```bash
npm install next-route-constants
# or
yarn add next-route-constants
```

## Usage

### 1. CLI Options (Recommended)

```bash
# Basic usage
yarn generate-next-route

# With options
yarn generate-next-route --output ./src/constants --name routes.ts --input ./src/app

# Short options
yarn generate-next-route -o ./src/constants -n routes.ts -i ./src/app
```

#### 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`)
- `-c, --config <path>`: Configuration file path (optional)

### 2. 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
};
```

**Note**: CLI options take precedence over configuration files.

### 3. Using Generated Constants

```typescript
import { ROUTES } from './constants/routes';

// Usage examples
console.log(ROUTES.Home); // '/'
console.log(ROUTES.User.Login); // '/user/login'
```

## Usage Examples

```bash
# Basic usage
yarn generate-next-route

# Custom output path
yarn generate-next-route -o ./lib/constants -n app-routes.ts

# Different app directory
yarn generate-next-route -i ./app -o ./constants

# All options
yarn generate-next-route \
  --input ./src/app \
  --output ./src/lib/constants \
  --name navigation.ts
```

## Features

### ⚠️ 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

### 1. Basic Routing
```
src/app/
├── page.tsx
├── route.json                 → { "name": "Home" } → { "Home": "/" }
├── about/
│   ├── page.tsx
│   └── route.json            → { "name": "About" } → { "About": "/about" }
```

### 2. Grouping via Inheritance
```
src/app/
├── posts/
│   ├── page.tsx
│   ├── route.json            → { "name": "Posts", "groupName": "Posts" }
│   ├── [id]/
│   │   ├── page.tsx
│   │   ├── route.json        → { "name": "Detail" } // Inherits "Posts"
│   │   └── edit/
│   │       ├── page.tsx
│   │       └── route.json    → { "name": "Edit" } // Inherits "Posts"

Result:
{
  "Posts": {
    "Posts": "/posts",
    "Detail": "/posts/[id]",
    "Edit": "/posts/[id]/edit"
  }
}
```

### 3. Inheritance Override
```
src/app/
├── posts/
│   ├── route.json            → { "name": "Posts", "groupName": "Posts" }
│   └── [id]/
│       ├── route.json        → { "name": "Detail" } // Inherits "Posts"
│       └── comments/
│           └── route.json    → { "name": "Comments", "groupName": "Comments" } // Override

Result:
{
  "Posts": {
    "Posts": "/posts",
    "Detail": "/posts/[id]"
  },
  "Comments": {
    "Comments": "/posts/[id]/comments"
  }
}
```

### 4. Dynamic Routing
```
src/app/
├── posts/
│   └── [id]/
│       ├── page.tsx
│       └── route.json        → { "name": "Detail", "groupName": "Posts" }

Result:
{
  "Posts": {
    "Detail": "/posts/[id]"
  }
}
```

### 5. Route Groups
```
src/app/
├── (auth)/
│   ├── login/
│   │   ├── page.tsx
│   │   └── route.json        → { "name": "Login" } → { "Login": "/login" }
│   └── signup/
│       ├── page.tsx
│       └── route.json        → { "name": "Signup" } → { "Signup": "/signup" }
```

## Generated File Example

```typescript
// This file is auto-generated. Do not edit manually.
// Generated on 2024-01-01T00:00:00.000Z
// Routes are configured via route.json files in each page directory

export const ROUTES = {
  "Home": "/",
  "About": "/about",
  "User": {
    "Login": "/user/login",
    "Profile": "/user/profile"
  },
  "Posts": {
    "Posts": "/posts",
    "Detail": "/posts/[id]",
    "Edit": "/posts/[id]/edit"
  }
} as const;

export type RouteKeys = keyof typeof ROUTES;
```

## Monorepo Support

The package automatically detects monorepo structures:
- Current project's `src/app`
- Current project's `app`
- Parent directories' `src/app` (up to 2 levels)

## Configuration Priority

1. **CLI options** (highest priority)
2. CLI `--config` specified configuration file
3. `route-constants.config.js`
4. `route-constants.config.ts`
5. Configuration extracted from `next.config.js`
6. **Default values** (lowest priority)

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Local testing
npm link
cd /path/to/test/project
npm link next-route-constants
yarn generate-next-route
```

## License

MIT