next-generate-path 0.0.1 → 0.0.3

package/README.md

@@ -2,25 +2,36 @@
 
 Type-safe `generatePath()` for Next.js. Autocomplete for every route, params enforced at compile time.
 
-Next.js [typed routes](https://nextjs.org/docs/app/api-reference/config/next-config-js/typedRoutes) give you type safety on `<Link href>`, `redirect()`, etc. — but dynamic routes like `/blog/[slug]` don't appear in autocomplete. You have to know the pattern and manually write template literals.
+## The problem
 
-`next-generate-path` fixes this. It gives you a single `generatePath` function with full autocomplete for **all** your routes and compile-time enforcement of the correct params.
+Next.js [typed routes](https://nextjs.org/docs/app/api-reference/config/next-config-js/typedRoutes) give you type safety on `<Link href>`, `redirect()`, etc. — but dynamic routes like `/blog/[slug]` don't appear in autocomplete. You have to know the pattern and manually write template literals. There's no way to discover what routes exist or what params they need.
+
+## The solution
+
+`next-generate-path` gives you a single `generatePath` function with full autocomplete for **all** your routes and compile-time enforcement of the correct params.
 
 ```tsx
 import { generatePath } from "next-generate-path";
 
 generatePath("/blog/[slug]", { slug: "hello-world" });
-// => "/blog/hello-world" — full autocomplete, params required
+//            ^ autocomplete shows all routes     ^ params are required and type-checked
 
 generatePath("/about");
-// => "/about" — no params needed
+// => "/about" — static routes need no params
 
 generatePath("/blog/[slug]");
-// TS error: missing required params
+// TS error: expected 2 arguments, got 1
 ```
 
 The return type is compatible with Next.js's `RouteImpl`, so it works directly with `<Link>`, `redirect()`, and `router.push()` — no casts needed.
 
+```tsx
+// All of these are fully type-safe
+<Link href={generatePath("/blog/[slug]", { slug: "hello" })}>Read post</Link>
+redirect(generatePath("/products/[id]", { id: "42" }));
+router.push(generatePath("/about"));
+```
+
 ## Setup
 
 ### 1. Install
@@ -40,7 +51,7 @@ const nextConfig = {};
 export default withTypedRoutes(nextConfig);
 ```
 
-That's it. `withTypedRoutes` enables `typedRoutes` and generates a declaration file that wires your app's routes into `generatePath` automatically.
+That's it. `withTypedRoutes` enables Next.js's `typedRoutes` option and generates a declaration file that wires your app's routes into `generatePath` automatically.
 
 ### 3. Use it
 
@@ -57,6 +68,8 @@ export default function Page() {
 }
 ```
 
+> **Note:** After first setup, run `next build` or `next dev` once to generate the route types. Autocomplete will work after that.
+
 ## Supported route types
 
 ### Static routes
@@ -66,7 +79,7 @@ generatePath("/about");
 // => "/about"
 ```
 
-### Dynamic routes
+### Dynamic routes — `[param]`
 
 ```tsx
 generatePath("/blog/[slug]", { slug: "hello-world" });
@@ -75,23 +88,46 @@ generatePath("/blog/[slug]", { slug: "hello-world" });
 
 ### Nested dynamic routes
 
+Params from parent segments are included:
+
 ```tsx
 generatePath("/products/[id]/reviews", { id: "42" });
 // => "/products/42/reviews"
 ```
 
-### Catch-all routes
+### Catch-all routes — `[...param]`
 
-Catch-all params accept `string[]` — segments are joined with `/`.
+Catch-all params accept `string[]` — segments are joined with `/`:
 
 ```tsx
 generatePath("/docs/[...segments]", { segments: ["guides", "routing"] });
 // => "/docs/guides/routing"
+
+generatePath("/docs/[...segments]", { segments: ["getting-started"] });
+// => "/docs/getting-started"
+```
+
+### API routes — `route.ts`
+
+API route handlers are included in the `ParamMap` too, so `generatePath` works for building API URLs:
+
+```tsx
+generatePath("/api/health");
+// => "/api/health"
+
+generatePath("/api/products/[id]", { id: "42" });
+// => "/api/products/42"
 ```
 
-### Route groups
+This is useful for `fetch` calls where you want type-safe API paths:
+
+```tsx
+const res = await fetch(generatePath("/api/products/[id]", { id: productId }));
+```
 
-Route groups like `(marketing)` don't affect URLs. A page at `app/(marketing)/pricing/page.tsx` is just `/pricing`:
+### Route groups — `(folder)`
+
+Route groups don't affect URLs. A page at `app/(marketing)/pricing/page.tsx` is just `/pricing`:
 
 ```tsx
 generatePath("/pricing");
@@ -103,28 +139,72 @@ generatePath("/pricing");
 Next.js with `typedRoutes: true` generates a `ParamMap` interface in `.next/types/routes.d.ts` that maps every route pattern to its params:
 
 ```ts
+// Generated by Next.js
 interface ParamMap {
   "/": {}
   "/about": {}
+  "/api/health": {}
+  "/api/products/[id]": { id: string }
   "/blog/[slug]": { slug: string }
+  "/products/[id]": { id: string }
+  "/products/[id]/reviews": { id: string }
   "/docs/[...segments]": { segments: string[] }
+  "/pricing": {}
 }
 ```
 
-`withTypedRoutes()` generates a small declaration file in `.next/types/` that merges this `ParamMap` into the package via [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation). Since `.next/types/**/*.ts` is already in your tsconfig's `include`, TypeScript picks it up automatically — no manual wiring needed.
+`withTypedRoutes()` generates a small `.d.ts` file in `.next/types/` that merges this `ParamMap` into the package via [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation):
+
+```ts
+// Auto-generated in .next/types/typed-routes.d.ts
+import type { ParamMap } from "./routes";
 
-The `generatePath` function uses conditional tuple types to require params only when the route has them, and returns a template literal type (e.g. `` `/blog/${string}` ``) that Next.js's `RouteImpl` accepts.
+declare module "next-generate-path" {
+  interface TypedRoutesParamMap extends ParamMap {}
+}
+```
 
-## `createGeneratePath` factory
+Since `.next/types/**/*.ts` is already in your tsconfig's `include`, TypeScript picks it up automatically — no manual wiring needed.
 
-If you're not using Next.js, or want to provide your own param map, use the factory:
+The `generatePath` function uses **conditional tuple types** to require params only when the route has them, and returns a **template literal type** (e.g. `` `/blog/${string}` ``) that Next.js's `RouteImpl` accepts — so the result works directly with `<Link>`, `redirect()`, and `router.push()`.
+
+## API
+
+### `generatePath(route, params?)`
+
+```ts
+import { generatePath } from "next-generate-path";
+```
+
+Returns the resolved URL string. Params are required for dynamic routes and omitted for static routes.
+
+- **`route`** — A route pattern string (autocompleted from your app's routes)
+- **`params`** — An object of param values (required when the route has dynamic segments)
+- **Returns** — The resolved URL, typed as a template literal compatible with Next.js's `RouteImpl`
+
+Param values are URI-encoded. Catch-all params (`string[]`) are joined with `/`.
+
+### `withTypedRoutes(config)`
+
+```ts
+import { withTypedRoutes } from "next-generate-path/next";
+```
+
+Wraps your Next.js config. Enables `typedRoutes: true` and generates the type bridge file.
+
+### `createGeneratePath<ParamMap>()`
 
 ```ts
 import { createGeneratePath } from "next-generate-path";
+```
+
+Factory for creating a `generatePath` function with a custom param map. Useful outside of Next.js or for testing:
 
+```ts
 type MyRoutes = {
   "/": {};
   "/users/[id]": { id: string };
+  "/docs/[...path]": { path: string[] };
 };
 
 const generatePath = createGeneratePath<MyRoutes>();
@@ -133,6 +213,12 @@ generatePath("/users/[id]", { id: "123" });
 // => "/users/123"
 ```
 
+## Requirements
+
+- Next.js 14+ with App Router
+- TypeScript
+- `typedRoutes` enabled (handled automatically by `withTypedRoutes`)
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-generate-path",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Type-safe route path generation for Next.js typed routes",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",