![](\"https://upload.wikimedia.org/wikipedia/commons/8/8e/Nextjs-logo.svg\"){kind=logo}
\n \n \n
![](\"./getRoute.gif\")
\n\n## Features\n\n- **Automatic route listing**. Avoid having to maintain a list of existing pages for your application\n- **Compile time route validation**. Avoid having to run your application to verify if links are correct, just use types\n- **Unopinionated**. Use our simple and composable utils or create your own abstraction\n\n## Installation\n\nInstall using yarn:\n\n```bash\nyarn add @axelraag/next-type-safe-routes\n```\n\nOr using npm:\n\n```bash\nnpm install @axelraag/next-type-safe-routes --save\n```\n\n> For an example setup, see the [`/example`](/example) folder\n\nThe easiest way to use `next-type-safe-routes`, is with [`next-compose-plugins`](https://github.com/cyrilwanner/next-compose-plugins). With `next-compose-plugins` installed, you can add a `next.config.js` file with the following content:\n\n```js\nconst withPlugins = require(\"next-compose-plugins\");\nconst nextTypeSafePages = require(\"next-type-safe-routes/plugin\");\n\nmodule.exports = withPlugins([nextTypeSafePages]);\n```\n\nWhen you start up your application, it will generate types for all of your pages and API routes and save them to the file `next-type-safe-routes/dist/utils.d.ts` in the package. The file will be updated whenever you add or remove pages and API routes.\n\nTo generate the types without starting the application, execute the command `next-type-safe-routes`. This may be necessary to use it in CI/CD that all test pass.\n\n```json\n{\n \"scripts\": {\n \"postinstall\": \"next-type-safe-routes\"\n }\n}\n```\n\n## Usage\n\nYou can now import the `getRoute` util from `next-type-safe-routes` and use it to retrieve a route that's is guaranteed to exist in your application.\n\n```ts\nimport { getRoute } from \"next-type-safe-routes\";\n\n// for simple routes (e.g. the file `/pages/users.tsx`)\ngetRoute(\"/users\");\n// for dynamic routes (e.g. the file `/pages/users/[userId]/page.tsx`)\ngetRoute({ route: \"/users/[userId]\", params: { userId: \"1\" } });\n// for catch all routes (e.g. the file `/pages/catch-all/[[...slug]].tsx`)\ngetRoute({ route: \"/catch-all\", path: \"/a/b/c\" });\n```\n\nNow you just need to decide how you want to integrate `next-type-safe-routes` in your project. If you want inspiration, we demonstrate how to create a simple abstraction for the Next.js `Link` and `router` in [the example project](/example/src).\n\n![](\"./example.gif\")
\n\n## How it works\n\nSince the Next.js router is based (strictly) on the file-system, we can determine which pages and API routes exists in an application simply by parsing the `/pages` folder. And due to the strictness, we can also determine which parameters are needed for dynamic routes.\n\nAs mentioned in the usage section, we generate a module declaration specific to your project when running your project. The output looks like this:\n\n```ts\ndeclare module \"next-type-safe-routes\" {\n export type TypeSafePage = ... // all your pages\n export type TypeSafeApiRoute = ... // all your routes\n export const getPathname = ... // typed based on your routes\n export const getRoute = ... // typed based on your routes\n}\n```\n\n> See [`/example/src/@types/next-type-safe-routes/index.d.ts`](/example/src/@types/next-type-safe-routes/index.d.ts) for a real example\n\nThe trick here is, that we override the types for `next-type-safe-routes`. And we (re)define the args accepted by the `getRoute` and `getPathname` to match the types for your project.\n\nThe declaration will be written to `@types/next-type-safe-routes/index.d.ts` in the root (determined by Next.js) of your project.\n\n## API reference\n\nHow you ensure that only links to existing pages is essentially up to you, but we do expose a few _tiny_ util methods to help you do this.\n\n#### The `getRoute` method\n\nA simple method that converts a type-safe route to an \"actual\" route.\n\n**Examples:**\n\n```ts\nimport { getRoute } from \"next-type-safe-routes\";\n\n// For simple (non-dynamic) routes\nconst route = getRoute(\"/users\"); // => \"/users\"\n\n// With query params\nconst route = getRoute({\n route: \"/users\",\n query: { \"not-typed\": \"whatevs\" },\n}); // => \"/users?not-typed=whatevs\"\n\n// For dynamic routes\nconst route = getRoute({\n route: \"/users/[userId]\",\n params: { userId: 1234 },\n}); // => \"/users/1234\"\n\n// For catch all routes\nconst route = getRoute({\n route: \"/catch-all\",\n path: \"/can/be/anything\",\n}); // => \"/catch-all/can/be/anything\"\n```\n\n> [Optional catch all routes](https://nextjs.org/docs/routing/dynamic-routes#optional-catch-all-routes) are also supported.\n\n#### The `getPathname` method\n\nThe `getPathname` works similarly to the `getRoute`. It just returs a [Next.js pathname](https://nextjs.org/docs/api-reference/next/router#router-object). For instance:\n\n```ts\nimport { getPathname } from \"next-type-safe-routes\";\n\nconst path = getPathname({\n route: \"/users/[userId]\",\n params: { userId: 1234 },\n}); // => `/users/[userId]`\n```\n\n#### The `TypeSafePage` and `TypeSafeApiRoute` types\n\nThese can be useful for making your own abstraction. For instance, if you want to make a tiny abstraction ontop of the `next/router`:\n\n```ts\nimport { TypeSafePage, getRoute } from \"next-type-safe-routes\";\nimport { useRouter as useNextRouter } from \"next/router\";\n\nconst useRouter = () => {\n const router = useNextRouter();\n\n // Say you only want to allow links to pages (and not API routes)\n const push = (typeSafeUrl: TypeSafePage) => {\n router.push(getRoute(typeSafeUrl));\n };\n\n return { ...router, push };\n};\n\nexport default useRouter;\n```\n\nFor basic routes, the type can be of the type `string` or:\n\n```ts\n{\n route: string,\n query?: { ... } // any key value pairs (not type-safe)\n}\n```\n\nAnd for dynamic routes, the type is always:\n\n```ts\n{\n route: string,\n params: { ... }, // based on the file name\n query?: { ... } // any key value pairs (not type-safe)\n}\n```\n\nAnd for [catch all routes](https://nextjs.org/docs/routing/dynamic-routes#catch-all-routes), a (non-typed) `path` will also be required (or optional for [optional catch all routes](https://nextjs.org/docs/routing/dynamic-routes#optional-catch-all-routes)):\n\n```ts\n{\n route: string,\n path: string,\n params: { ... }, // based on the file name\n query?: { ... } // any key value pairs (not type-safe)\n}\n```\n\n**Examples**:\n\n```ts\ntype Query = { [key: string]: any };\nexport type TypeSafePage =\n | \"/users\"\n | { route: \"/users\"; query?: Query }\n | {\n route: \"/users/[userId]\";\n params: { userId: string | number };\n query?: Query;\n }\n | {\n route: \"/users/[userId]/catch-all-route\";\n params: { userId: string | number };\n path=\"/catch/all/path\"\n query?: Query;\n };\n```\n\n> Note, the `TypeSafePage` and `TypeSafeApiRoute` are kept separate even though they are essentially the same type. We do this, as you may potentially want to distinguish between them in your application.\n\n## Motivation\n\nAt my company, [Proper](https://helloproper.com/), we like pages. Like...a lot! Our platform is a fairly large Next.js application consisting of ~70 pages. And we link between pages ~200 places in the application.\n\nWe find that having pages make features easily discoverable by end-users and developers alike. And having pages (urls) for each of our features help us maintain a sane information architecture throughout our platform.\n\nThe [Next.js file-system based router](https://nextjs.org/docs/routing/introduction) help us stay consistent and organised around our pages. But we've had some incidents where our application was released with dead links.\n\nAt one point, a file in the `/pages` folder was renamed and we simply overlooked (forgot to change) some of the links to that page. Another time, a bit of \"clever\" string concatenation caused an issue. In this case, we had moved a page, and failed to update all links to the page correctly due to the concatenated links.\n\nWith the `next-type-safe-routes`, we're trying to mitigate this issue. The plugin gives us confidence when refactoring as well as a top notch developer experience.\n\n> We considered something like the [`next-routes`](https://github.com/fridays/next-routes) approach, but we don't want to manually have to maintain a list of routes in the application. We prefer conventions to be enforced when possible.\n","readmeFilename":"README.md"}![\"\"](\"https://img.shields.io/npm/v/next-type-safe-routes.svg?style=for-the-badge&labelColor=000000\")
\n ![\"\"](\"https://img.shields.io/npm/l/next.svg?style=for-the-badge&labelColor=000000\")
\n