Export dynamic routes to allow an appropriately-configured, non-Next.JS web server to serve an app

[miceg]

Goals

It should be possible to serve a statically-generated Next.JS Page Router app which incorporates dynamic routes using an appropriately configured, non-Next.JS web server.

To do that, the Next.JS pipeline needs to export the dynamic routes used by the application, so that web server (or a config generation tool) can have appropriate URL rewriting rules in place.

While Next.JS does some partial component fetching trickery to handle internal links, the URLs don't actually work without hitting one of the real statically-generated pages.

Non-Goals

• Altering Next.JS build pipeline to build a true (monolithic) single-page app.
• Supporting App Router: [NEXT-1550] App Router with output: export does not support useParams() on client #54393
• Functional code changes

Background

Next.JS' build pipeline already exports .next/routes-manifest.json which contains all the details needed. This does not appear to be formally documented, outside of type definitions (RoutesManifest).

This appears to be used by:

• Next.JS' build process
• Parts of Vercel's Next.JS deployment process (based on error reports here and elsewhere)
• next-nginx-routes to build nginx URL rewrite configs
• Netlify's next-runtime
• many others

The "API", as it were, already exists and has already shipped: it's already adopted by first and third-party users. It's no longer an "internal implementation detail". 😄

Related works

• This example uses client-side fetches with dynamic routes, for which rewriting rules are the missing piece.
• Gatsby's client-only routes have a routesManifest API for deployment adaptors.

Proposal

The request is that there should be an actual specification, which would formalise the status quo:

1. (main goal) There should be documentation on Next.JS website (like there is for function and file conventions).

   Vercel likely already have an internal document for this, so are the best positioned group (and possibly only group) to work on that.

   It is recognised that it would require some clean-up before publication.

2. (nice to have) The RoutesManifest type should be exported as a stand-alone package, and Next.JS should depend on it.

   This would allow other packages (like next-nginx-routes and Vercel's build infrastructure) to strongly depend on these types.

   It would also allow Next.JS developers to discover downstream public uses of routes-manifest.json, to understand use-cases for that data, and allow them to test future changes.

   Ownership of this package should remain with Next.JS maintainers.

The alternative here is that things stay as-is, which without a specification, which risks breaking external users without warning.