next-routes-typed

Generate type-safe route utilities for Next.js app router. Automatically generate route constants and helper functions that match your app directory structure.

🌟 Features and Why next-routes-typed?

• ✨ Type-safe route generation: Full TypeScript support with type inference
• 🎯 App Router Support: Built for Next.js 13+ app directory
• 🔄 Dynamic Routes: Support for [param], [...catchAll], and [[...optional]]
• 📁 Route Groups: Support for route groups (folders in parentheses)
• 🌍 i18n Ready: Perfect for internationalized applications
• 🛠️ Zero Config: Works out of the box with your existing Next.js structure
• 🎨 Developer Experience: Great autocomplete and type checking
• 🔒 Type Safety: Catch routing errors at compile time
• 🚀 Performance: Zero runtime overhead
• 📦 Lightweight: No dependencies

🚀 Getting Started

npm install --save-dev next-routes-typed
# or
yarn add -D next-routes-typed
# or
pnpm add -D next-routes-typed

📘 Usage

Basic Usage

Run in your Next.js project root:

npx next-routes-typed

This will generate a routes.ts file in src/lib by default.

CLI Options

npx next-routes-typed --help

Options:
  -o, --output <path>       output directory (default: "src/lib")
  -f, --filename <name>     output filename (default: "routes.ts")
  --prettier-config <path>  path to prettier config
  --debug                   enable debug logging
  -h, --help               display help for command

Example

For a Next.js app structure like:

app/
├── page.tsx
├── about/
│   └── page.tsx
├── blog/
│   ├── page.tsx
│   └── [slug]/
│       └── page.tsx
└── products/
    └── [category]/
        └── [id]/
            └── page.tsx

next-routes-typed will generate:

export const routes = {
  home: {
    path: "/",
  },
  about: {
    path: "/about",
  },
  blog: {
    path: "/blog",
  },
  blogSlug: {
    path: "/blog/[slug]",
    params: {
      slug: "",
    },
  },
  productsCategoryId: {
    path: "/products/[category]/[id]",
    params: {
      category: "",
      id: "",
    },
  },
} as const;

export type AppRoutes = keyof typeof routes;

export function createUrl(
  route: AppRoutes,
  params?: Record<string, string>,
  query?: Record<string, string>
): string;

Using Generated Routes

import { createUrl } from "@/lib/routes";

// Simple route
const aboutUrl = createUrl("about");
// Result: /about

// Route with parameters
const blogPostUrl = createUrl("blogSlug", { slug: "hello-world" });
// Result: /blog/hello-world

// Route with parameters and query
const productUrl = createUrl(
  "productsCategoryId",
  { category: "electronics", id: "123" },
  { ref: "homepage" }
);
// Result: /products/electronics/123?ref=homepage

🎯 Supported Route Types

• Basic routes: /about
• Dynamic routes: /blog/[slug]
• Catch-all routes: /docs/[...slug]
• Optional catch-all routes: /docs/[[...slug]]
• Route groups: (marketing)/blog
• Parallel routes: @modal/login
• Intercepting routes: (.)photo

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License.

📢 Support

• 🐛 For bugs and feature requests, please create an issue
• 💬 For questions and discussions, please use GitHub Discussions