Expose typedRoutes route builder function

[nirtamir2]

Goals

1. Create a public function that allows creating type-safe routes to next.js and has static parameter string as param, and dynamic object for dynamic params)
2. Finding all paths to a given route easily with static string.
3. Compound dynamic routes more easily without parameter confusion - because we can add names and the parameter order does not matter to the caller.

Non-Goals

1. Add breaking changes to the existing typeRoutes type
2. Enforce the usage of the new paths function

Background

In Next 13.2 we added https://nextjs.org/docs/app/api-reference/next-config-js/typedRoutes which enables type-safe routing. Next.js can statically type links to prevent typos and other errors. This is a nice addition.

Before it happen, I use https://github.com/Schniz/next-static-paths (which became deprecated because after typeRoutes was introduced). It allows me to define routes in a type-safe way (as long as you run the generate command before adding new pages). I like its interface - a function pathFor that accepts two params:

1. A static string literal - that represents the route name/path in a searchable and readable way.
2. An object to define the dynamic params named after the dynamic slots.

For example: pathFor("/[tenantId]/settings/branding", { tenantId }) will return /${tenantId}/settings/branding string.

It shines when we have multiple params and we don't really care about the path order structure as much as we care about navigating to the right route.
For example: pathFor("/[tenantId]/bases/[baseId]/[tableId]/[viewId]", {tableId, tenantId, baseId, viewId,}) instead of /${tenantId}/bases/${baseId}/${tableId}/${viewId}. The user may type it wrong like /${tenantId}/bases/${baseId}/${viewId}/${tableId} and typedRoutes won't catch it.
Typing pathFor("/[tenantId]/bases/[baseId]/[tableId]/[viewId]", {tableId, tenantId, baseId: viewId, viewId: baseId,}) is more noticable.

Also - when moving files to change route structure with dynamic params - pathFor static params make it easier to refactor. Just search the static string. We cannot search for /${tenantId}/bases/${baseId}/${viewId}/${tableId} because no one guaranteed that the baseId dynamic path segment will be called in the same way as the variable baseId.

Similar maintained projects are that tackles this issue are

• https://github.com/tatethurston/nextjs-routes - which supports app directory.
• https://github.com/ckastbjerg/next-type-safe-routes
• https://github.com/sandulat/routes-gen - works for remix and solid-start. It works elegantly under the hood by using solid-start / remix routes cli commands internally.

The drawback of those libraries is that we need to either run a script to generate the .d.ts file manually, and we cannot be sure they won't break as next.js changes in the future.

Proposal

Expose function from next (or nested packages) named route / pathFor.
The function hsould return a string that represents a valid page route. Its type will be the same type as Route type from typedRoutes feature.
It will have a static string as a param - for better searchablility and an object for dynamic paths.
This function will be generated at the same time typedRoutes feature generate Routes type.

• The string param will be the same as the route path for static pages ( route("/static") will result "/static")
• The dynamic part will be represented in a meaningful static way in the first param - like [dynamicPart] syntax. It's better to make it deterministic (only one valid syntax for a single param) and as close as possible to the next.js file structure (so it will be easy to understand). I suggest `route("/dynamic/[userId]", { userId: "123" }).
• We will be able to infer the available dynamic object params
• It should support the app router

Same as https://github.com/Schniz/next-static-paths, maybe a different name (route?), but exposed from next.js and support app router.

[osdiab]

Agreed with this - I think the builder function API is easier to use, and also the Intellisense in-editor from it is much better than what you get from the current string interpolation system.

[nirtamir2]

I currently solved it by creating a fork of next-static-paths (see https://github.com/nirtamir2/next-static-paths), but I wish it would be as part of next itself

[osdiab]

tried it out and seems to be working! i'll contribute to your library if we find anything that doesn't work properly. Also hooked it up to chokidar-cli to auto-generate when new routes are created/removed. Honestly I hope Vercel decides to support this type of pattern rather than the current one since it's way better DX in my opinion.

[Ziothh]

I have created a discussion (#55499) with a broader scope, which is why I didn't extend this thread.
I did mention this discussion in the 'Background' section.

For that discussion I've written a proof of concept that allows such a function to easily be created by both library authors and / or next.js itself.

Feedback would be welcome.