In a meta-framework's build output, what does a route manifest contain, and what depends on it at runtime?

File-based routing is an authoring convenience: a URL is answered by whatever module sits at the matching place in the project. That is pleasant to write and useless at runtime, because nothing is going to walk a source tree to answer a request - and in many deployments the source tree is not even present. The build therefore turns the implicit table into an explicit one and writes it into the output. That artefact is the **route manifest**. ## What an entry holds A typical entry carries four things: - **A URL pattern**, with literal segments, parameterised segments and any catch-all distinguished from each other. - **A resolution target**: a prerendered document on disk, or a handler inside the server bundle. - **An asset list**: the chunks and stylesheets that route needs, by their emitted, content-hashed names. - **Flags**: whether the route was prerendered, whether a separate data endpoint accompanies it, whether middleware must run before it resolves. Most builds also emit an **asset manifest** - a mapping from logical entry names to the files actually emitted for them. The two answer different questions ("which route?" versus "which file?"), and some builds merge them into one document. ## Why it cannot be recomputed at request time Three reasons, each sufficient on its own: 1. **Hashed names are not knowable from source.** An asset's name is derived from its emitted bytes, so only the build that produced them can record the mapping. 2. **Prerendering was decided at build time.** Whether a URL exists as a document is a fact about that build, not about the route's source. 3. **Match ordering was computed once.** When a literal segment and a parameterised one could both match, precedence has to be resolved consistently; freezing that ranking into the manifest means every instance resolves the same URL the same way, independent of file-system iteration order. ## Who reads it | Reader | What it takes from the manifest | |---|---| | The server bundle's dispatcher | Which handler or document answers this URL, and what must run first | | Generated and prerendered HTML | The hashed filenames to reference and to hint as preloads | | The client router | Which route a link resolves to, and which chunks that route needs | The client router's use is the one people forget. Without a route table in the browser, a link click would have to navigate first and only then discover what to download - one round trip to learn, another to fetch. With the manifest, the router can resolve a link the moment it appears or is hovered, and start fetching the route's chunks while the user is still deciding. Per-route chunking falls out of the same structure: a file-based router gives the build a natural set of entry points, so each route's code lands in its own chunk and the manifest records which chunks belong to which route. ## When it is wrong - **A route exists in the output but not in the manifest.** The dispatcher has nothing to match, so the URL is not answered from that document even though the bytes are on disk. - **The manifest is from a different build than the assets.** It names files that no longer exist, so the references it hands out cannot be fetched. - **Someone assumes authoring order is match order.** Precedence is computed from specificity, not from the order files happened to be read; reasoning from the directory listing produces confident, wrong predictions about which route wins. ## A note on variation Meta-frameworks differ in how public this file is. Some document its shape as a contract that deployment tooling may read; others treat it as an internal detail that changes freely between versions and expect you to go through their own translation layer instead. Depend on the concept - an explicit, build-time route table that both sides of the app resolve through - rather than on a particular file's layout, and check before writing a script that parses one. They also differ in how much of the table reaches the browser. Shipping every entry makes link resolution instant but grows with the site, so a large site may ship a pruned or lazily fetched table and accept a lookup before some navigations. That is a size-versus-latency tradeoff, and it is worth knowing which one your framework made before blaming a slow first navigation on the network: - **Whole table shipped**: every link resolves locally, at a cost that scales with route count. - **Table fetched in pieces**: constant initial cost, with an occasional lookup before navigation. - **No client table at all**: navigation falls back to a full document request, which is a deliberate choice for content sites rather than a bug.