RFC: experimental.typedRoutes feature extensions

[Ziothh]

Goals

Enhancing the router types via the typedRoutes experimental feature.

As an outsider it feels like routing types have been on back burner for next.js.
In a large project with a lot of routes it is easy to forget what (query) parameters a URL needs.

typedRoutes feels like a good start but it could be much more extensible.
The current implementation mainly focuses on manually creating string literals.

Here are the main goals:

• enhance the route types for next.js primitives
• give library developers more power without needing to write a webpack plugin (because most of the groundwork is already here)

Author's note

I am more than willing to open a PR and implement these changes myself. I realise the next.js dev team is busy enough as is.

Background

Internal

This is meant to extend the work that @shuding has already done.
The webpack plugin's source code can be found at /packages/next/src/build/webpack/plugins/next-types-plugin.

If the feature is enabled, the plugin generates this file:

// MY_NEXT_APP_ROOT/.next/types/link.d.ts

declare namespace __next_route_internal_types__ {
  /* Snip ... */

  // Static routes for both the app and pages router
  type StaticRoutes =
    | `/`
    | `/todos`
  // Dynamic routes for both the app and pages router
  type DynamicRoutes<T extends string = string> =
    | `/todos/${SafeSlug<T>}`
    | `/users/${SafeSlug<T>}`

  type RouteImpl<T> =
    | StaticRoutes
    | SearchOrHash
    | WithProtocol
    | `${StaticRoutes}${SearchOrHash}`
    | (T extends `${DynamicRoutes<infer _>}${Suffix}` ? T : never)

  /* Snip ... */
}


declare module 'next' {
  /* Snip ... */

  export type Route<T extends string = string> =
    __next_route_internal_types__.RouteImpl<T> // Uses the generated types

  /* Snip ... */
}

Third-party

There exists a next-type-safe-routes package.
The last update is from 1 year ago and it does not support app dir.
This probably was created before the typedRoutes experimental feature was released.

Related discussions

'Expose typedRoutes route builder function' proposes a route builder function to be included by next.js.
This is only a small part of my proposal and third party libraries could easilly accomplish this is the first part of my proposal would be implemented.

Proposal

I've created a mock PR in my fork, so you can easily see the code changes.
I would gladly contribute myself.

In this discussion I'll outline some ideas and would love to hear your feedback on them.

General

I've added a temporary PoC_Routes namespace that gets generated at compile time.
This namespace is used distinguish shudding's and my types from each other.

All proof of concept code can be found in /dev/app/{lib, examples}.

I'm well aware there are some caveats to my code. Some examples:

• Catch-all routes are not supported (but could be with some minimal effort)
• Routes with multiple occurrences of the same parameter name (e.g. '/users/[id]/todos/[id]') are not supported.

I've written code for proposals 1..=3. The 4th proposal mainly lives in my head right now because I'm not sure if it's the right way to implement it.

1. Separate app and pages route raw types

I've adjust the webpack plugin to also generate the following code:

// MY_NEXT_APP_ROOT/.next/types/link.d.ts

declare module 'next' {
  /* Snip... */

  // Types generated by custom code for this proposal
  export namespace PoC_Routes {
    /** App dir routes */
    export type AppRoutes =
      | '/'
      | '/todos'
      | '/todos/[id]'

    /** Pages dir routes */
    export type PageRoutes =
      | '/users/[id]'

    /** App and page routes combined */
    export type AllRoutes = AppRoutes | PageRoutes
  }

  /* Snip... */
}

typedRoutes currently does not distinguish between app and pages routes.
It would be handy to separate them for library developers creating router wrappers (e.g. solito)

2. A function to create type safe routes

This would further the 'Expose typedRoutes route builder function' feature request.

If the first proposal were to be implemented, library authors could make this function easily but I like the idea of this being standardized by next.js itself.

Here my implementation in action: (source code can be found here)

// /dev/app/examples/createUrl.ts

// @ts-expect-error
createUrl('/foo/[bar]', {}) // '/foo/[bar]' is not a valid route

// @ts-expect-error
createUrl('/todos', {
  params: { id: '15' }, // It's a static route. 'params' is not a valid config option
  query: { hello: 'world' },
  hash: 'section-1',
})

createUrl('/todos/[id]', {
  params: { id: '15' },
  query: { hello: 'world' },
  hash: 'section-1',
}) // '/todos/15?hello=world#section-1'

3. Router type enhancements

This would require some changes to the router source code so this probably won't get implemented.
Still, this could be third-party library by some external developer.

Source code:

• index
• routers
• link

I've enhanced the following next.js primitives to use the createUrl function.

3.1 Pages router

The pages router already takes in string | URL as its first parameter.
I've added the data needed for createUrl as a valid option

PagesDir source code

// /my-app/src/pages/some-page.tsx

'use client'

import type { FC } from 'react'
import { PagesDir } from '~/lib'

const PagesComponent: FC = () => {
  const pagesRouter = PagesDir.useRouter()

  /// Example with static path
  pagesRouter.push({
    path: '/todos',
  })

  /// Example with dynamic path
  // TypeScript warns about the missing 'id' parameter
  // @ts-expect-error
  pagesRouter.push({
    path: '/todos/[id]',
  })

  pagesRouter.push({
    path: '/todos/[id]',
    params: { id: 'hi' },
  })

  return null
}

export default PagesComponent

3.2 App router

AppDir source code

// /my-app/src/app/some-page/page.tsx

import type { FC } from 'react'
import { AppDir } from '~/lib'

const AppComponent: FC = () => {
  const appRouter = AppDir.useRouter()

  appRouter.push('/todos', {
    // 'params' does not exist because it's a static route
    query: { hello: 'world' },
    hash: 'foo',
  })

  return null
}

export default AppComponent

3.3 Link

Link source code

// /my-app/src/features/todos.tsx

import type { FC } from 'react'
import { Link } from '~/lib'

export const TodoLink: FC<{ id: string }> = ({ id }) => (
  <Link
    href={{
      route: '/todos/[id]',
      params: { id },
    }}
  >
    Goto todo({ id })
  </Link>
)

4. Typed query parameters

It would be very handy if we could define the query parameters for a given route.

Something like route segment config comes to mind.

An example:

// /my-app/src/app/**/page.tsx

// Native next.js route segment config
export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'
export const maxDuration = 5

// Proposal:
export interface Query {
  hello: string
  filters?: string[]
}
// Bit far fetched but the same could be done for params on a dynamic route segment.
// E.g. '/my-app/src/app/todos/[id]/route.ts'
// export type Param = number | `${number}`


export default function MyPage() { return null }

This could be parsed into the PoC_Routes definitions

// MY_NEXT_APP_ROOT/.next/types/link.d.ts

declare module 'next' {
  /* Snip... */

  export namespace PoC_Routes {
    export type AppRoutesConfig = {
      '/': {},
      '/todos': {
        query: {
          hello: string,
          filters?: string[],
        } // Parsed from `MY_NEXT_APP_ROOT/src/app/todos/page.tsx`
      },
      '/todos/[id]': {
        params: { id: string },
        query: { hello?: string } // Parsed from `MY_NEXT_APP_ROOT/src/app/todos/[id]/page.tsx`
      }
    }
    
    export type AppRoutes = keyof AppRouteConfig

    /* Snip... */
  }

  /* Snip... */
}

5. Exporting routes as javascript arrays

This is optional but I can't think of a reason why not to.
It isn't supported right now because the types are generated in types.d.ts, which uses declare module magic to override types.

It could, however, be useful to some library author to access these. There would be next to no build performance penalty, because most of the needed work is already there.

Example use case:
I have written a dev overlay that uses a route map, generated by a Rust CLI to quickly navigate between pages without the need of a navbar. If this was freely available, I wouldn't have needed to write the Rust CLI.

Some example generated output:

// /.next/routes.js

export const PAGES_ROUTES = ['/users', '/users/[id]']
export const APP_ROUTES = ['/todos', '/todos/[id]']

export const ALL_ROUTES = [/* both arrays combined */]

[RJWadley]

This would be a big improvement for me. I've put quite a bit of effort into making my next routing as type safe as possible, but I can only take it so far. Now that TanStack Router is out, I'm once again reminded of how nice type-safe routing is and I want it :)

Here's some thoughts on part 3:
It's really helpful to have a type that represents any valid link, for passing links around functions and such. In the current implementation, that is something like type ValidLink<T> = RouteImpl<T> | UrlObject. Having this as a generic is necessary when working purely with strings, but makes using this type awkward (and still not even fully type safe, actually).

With the new route builder, the generic could at least be optional, which would be significantly more ergonomic: type ValidLink<T = never> = RouteImpl<T> | UrlObject | RouteBuilderOptions. This could even be non-breaking.

I do think the syntax could be a bit more consistent between the three options though. My favorite is the syntax on the 3.3 (link component), although the syntax in 3.1 could work as well. Not a big dealbreaker though. We should probably also update types of redirect and revalidatePath to use the same type.

here's what that would look like in my mind, by the way

App Router using the same syntax as Link:

// /my-app/src/app/some-page/page.tsx

import type { FC } from 'react'
import { AppDir } from '~/lib'

const AppComponent: FC = () => {
  const appRouter = AppDir.useRouter()

  appRouter.push({
    route: '/todos',
    query: { hello: 'world' },
    hash: 'foo',
  })

  return null
}

export default AppComponent

Pages Router using the same syntax as Link:

// /my-app/src/pages/some-page.tsx

'use client'

import type { FC } from 'react'
import { PagesDir } from '~/lib'

const PagesComponent: FC = () => {
  const pagesRouter = PagesDir.useRouter()

  /// Example with static path
  pagesRouter.push({
    route: '/todos',
  })

  /// Example with dynamic path
  // TypeScript warns about the missing 'id' parameter
  // @ts-expect-error
  pagesRouter.push({
    route: '/todos/[id]',
  })

  pagesRouter.push({
    route: '/todos/[id]',
    params: { id: 'hi' },
  })

  return null
}

export default PagesComponent

And redirect, using the same type:

// /my-app/src/app/hello-world/page.tsx

export default async function MyPage() {
  const session = await auth()
  if (!session) {
    redirect({
      route: "/login",
      query: { then: "/hello-world" },
    })
  }

  return "hello world"
}

As for part 4, there's already syntax for defining searchParams that we can draw from:

export default function MyPage({
  searchParams: { hello },
}: {
  searchParams: { hello?: string; page: number }
}) {
  return null
}

The syntax is already there, so might as well use it. Ideally, there would be some processing and validation to support types like number or Record, but that might be a bit out of scope for these changes.

[Ziothh]

@RJWadley Thanks for the feedback!

About this discussion

It's really helpful to have a type that represents any valid link, for passing links around functions and such. In the current implementation, that is something like type ValidLink<T> = RouteImpl<T> | UrlObject. Having this as a generic is necessary when working purely with strings, but makes using this type awkward (and still not even fully type safe, actually).

I'd personally just do away with the whole RouteImpl<T> type because it doesn't give any autocompletion for dynamic routes.
Does Routes.Valid provide the types you want (see example below)?

I do think the syntax could be a bit more consistent between the three options though. My favorite is the syntax on the 3.3 (link component), although the syntax in 3.1 could work as well. Not a big dealbreaker though. We should probably also update types of redirect and revalidatePath to use the same type.

You're right. The pages router and Link component can probably use the same structure and 3.3 also is my preferred one of the two.
The app router does have a different API that can't be changed without being breaking.

I'm not too picky about the syntax and would just implement what the majority people like.
My preferred syntax atm (for ease of use and simple LSP autocompletion) is this:
(ideally for createURL, redirect, app & pages router but that'd be a breaking change)

// Examples
const router = Routes.useRouter()
router.push('/') // ok
router.push('/', { query: { hello: 'world' }, scroll: true }) // ok
router.push('/todo/[todoID]') // Error "expected 2 arguments but got 1"
router.push('/todo/[todoID]', { params: { todoID: 'uuid' } }) // ok

namespace Routes {
  export type Static = '/'
  export type Dynamic = '/todo/[todoID]'
  export type All = Routes.Static | Routes.Dynamic
  export type getParams<Route extends Routes.Dynamic> = /* Parse params from route here */ Record<string, string | string[]>

  export type Valid =
    | Routes.All
    | `${string}://${string}` // External links (e.g. "https://google.com")
    /* | ''              // Maybe allow "" to just quickly change query params: */
    /* | (string & {})   // Optional if you don't want to be strict */

  export type Options = {
    query?: Record<string, string>
    hash?: string
    /* App / Pages router options here if this is used in a hook */
  }

  export function useRouter() {
    return {
      // Would use same syntax as createURL(route, options) utility
      push<T extends Routes.Valid>(
        route: T,
        ...args: T extends Routes.Dynamic
          ? [options: Routes.Options & { params: Routes.getParams<T> }]
          : [options?: Routes.Options]
      ) {},
    } as const;
  }
}

My library

@next-typed-routes/lib: https://github.com/Ziothh/ntr/tree/master/lib

Because this topic didn't seem to get any traction I've created a library that implements what's discussed here.

It is still a WIP because I'm not yet sure how I'd like to structure my APIs.
I'll finish it in a month or so if you're interested

[chungweileong94]

Build something similar for my use case, the current typedRoute just wasn't enough, as soon as you have a "catch-all" route, the type is pretty much useless.

https://www.typescriptlang.org/play?#code/PTAEBUHkBFILlAYQE4FMCGAXVp2gOaoB2qyWA9sqJuQcaVjpgBZMCeADjgGbLkC21VqG4BLADY4AzpmQBXAMaY5aAFCZOOAErk52UAF5VoE6AA+oAOTBL5q8FHZ+U4AG1RAEwC6ti9fRu6F7AAEZuIT4A3KrqmqAA4qiYOnqoAAroZPwA0qhsUgA84AA0oFqoUnLimIagJABupAB8teCgqAAe2EQeUqAABgAkAN4yyKJE+AC+riMT3KSgGVlTXnNEC1TlMlP9xqYA-AlJKdjL6Dl5hduYpdtVNRbn-E37Jgj31dGxXEtYzJAOJhROQiIU2p1ur0yrpsC0DKBhm9QHxUghwNFTKApBhkApmM8pAcPqgFJQPAUxhN8KUqZMmtEpqAAGSgAAUiWSsPSmQuuXyRRakOI0IaiyOwxR3MJxLqqEaVCZCElqLOvOcJLJyApnNOPKy-PBTVpsmpLSmAEpvsAAFQ24w2pBoRigDj-IgXHiUKWpKQO4CqTocSg1bhyIhKEFEUCDN0sIrtLoivp6pps8hAqNSBAZFiA4Ggo0WxHIyQ1VWoBB0-C1DMFsEAOgrmNMom47LrWab0vVUmLSKxWO43rZZLBNVcAGs8qV6uhxHJUF5QOR25AQgArUmYBvEU0VSmm+npzOF7upQkW-vIwemCu10+NitN1AccToBSoNn9WbDadsVZ+lnedFytG9TCmZFIKxNsO0fKQGxxTJ8UvEtbxMe8AGoEX6A4RhIAB3UAAFUtAAGQAZVxFDexPesEKQvECV7C0GxoCij3wNkLV2FsTGgu8khUaNm1USCYhAUAAFoZNkuT5IUxS5JiMcZGoCpMAARlqWN-jZFVuQQfxAmCMJXAiSxSgrQllVwIzNMs0AQiMgAmWwmUtVRVJqbAZBcnS42YfSfWwIyHCcFx3G8RzrN7WzPHs9zQE87z1JkABmAK9IMtF7Hci1VCAA

[kristian240]

Can some one help with this one? #63779

[ravinggenius]

I'm really liking this proposal! This is exactly the direction I'd like to see typed routes go, the sooner the better.

I'd like to push back a little on 4. Typed query parameters though. Typescript cannot provide any runtime guarantees about query string types. The params are always typed as string because they are strings, and if the param is missing the route simply won't match. Query strings should be expected to be any shape (missing keys, extra keys, typoed keys), but the values are always strings, because the user may freely edit them. (I promise I read an older discussion about typing other request objects, and strongly typed request body was rejected for the same reason.) What you can do for strongly typed query strings is to pass the query object through zod (or similar). This will give you real type safety at runtime.

To go along with extending Next's route segment config, we could have the types provided by zod schemas instead of Typescript interfaces:

import { PageProps } from "next"; // i made this up, but it would be nice
import { z } from "zod";

export const PARAMS = z.object({
  id: z.coerce.number()
});

export const QUERY = z.object({
  hello: z.string(),
  filters: z.array(z.string()).optional()
});

export default function MyPage({
  params, // typed as { id: number; }
  query // typed as { hello: string; filters?: Array<string>; }
}: PageProps<z.infer<typeof PARAMS>, z.infer<typeof QUERY>>) { // or perhaps PageProps<typeof PARAMS, typeof QUERY>
  return null;
}

I don't know what should be expected if either PARAMS or QUERY fails to parse at runtime. Showing some kind of error page makes the most sense. If PARAMS fails to parse, showing not-found.tsx seems to make the most sense. If QUERY fails to parse, show error.tsx. Otherwise the type guarantees won't hold. Also the zod schemas I show here are very basic. They could easily be much more robust with default values et cetera if desired.

---

This is cool and I want it, but I wouldn't expect PARAMS or QUERY types to have any bearing on the rest of this proposal. Though now that I think about it, it would be very nice if these types where incorporated with the types used for 2. A function to create type safe routes and 3. Router type enhancements.

---

Edit: clarify error handling

[takashimamorino]

Thank you awesome extension.

I would like to use with /assetPrefix .
So, How do I add this string to the beginning of a path specification?