Postlude's pages are files in a folder. A tool scans that folder and writes apps/web/src/routeTree.gen.ts, a generated file that lists every page and, at the bottom, tells TypeScript what addresses exist so that a typo in a link is a compile error rather than a dead link at runtime. That file is committed to the repository.
There are two ways to regenerate it, and they do not produce the same thing. The build (bun run build) writes the complete file. The standalone script (bun run generate-routes) writes it without the last nine lines — the block that teaches TypeScript the list of addresses.
What goes wrong in practice: someone adds a page, runs the script the app's README points at, and commits. The committed file now has no address list. Every typed link in the app loses its checking, silently — nothing errors, because the type it falls back to accepts anything. The next build puts the nine lines back, so the loss shows up as an unexplained diff rather than as a failure, and whoever sees it has no reason to connect it to the script they ran.
Who this affects and what it costs to leave alone: one developer, occasionally, on a repository whose page count is about to grow. The cost is a confusing diff and a window in which link typos compile. It is cheap to leave alone today and gets more expensive as pages accumulate.
This is not caused by any recent change. It reproduces on 1933ee2, before the design work. It is filed now because apps/web/README.md was recently updated and points readers at that script, which makes it likelier to be run.
Evidence. apps/web/package.json defines generate-routes as the tsr generate CLI. The Vite plugin that runs during a build is configured separately in apps/web/vite.config.ts. The trailing block in apps/web/src/routeTree.gen.ts is a declare module '@tanstack/react-router' augmentation that registers the route tree; only the build's configuration produces it. The file is tracked — confirmed with git ls-files.
Suggested verification. From a clean checkout: bun run generate-routes, then git diff apps/web/src/routeTree.gen.ts. The nine-line block at the end of the file disappears. Then bun run build and diff again — it returns.
Likely fix: either give the standalone script the same configuration the build plugin uses, or drop the script and document the build as the only way to regenerate. Deciding between them is a small architectural call about whether a standalone regeneration step should exist at all.
Surfaced by the verification pass on #15. See #15.
Postlude's pages are files in a folder. A tool scans that folder and writes
apps/web/src/routeTree.gen.ts, a generated file that lists every page and, at the bottom, tells TypeScript what addresses exist so that a typo in a link is a compile error rather than a dead link at runtime. That file is committed to the repository.There are two ways to regenerate it, and they do not produce the same thing. The build (
bun run build) writes the complete file. The standalone script (bun run generate-routes) writes it without the last nine lines — the block that teaches TypeScript the list of addresses.What goes wrong in practice: someone adds a page, runs the script the app's README points at, and commits. The committed file now has no address list. Every typed link in the app loses its checking, silently — nothing errors, because the type it falls back to accepts anything. The next build puts the nine lines back, so the loss shows up as an unexplained diff rather than as a failure, and whoever sees it has no reason to connect it to the script they ran.
Who this affects and what it costs to leave alone: one developer, occasionally, on a repository whose page count is about to grow. The cost is a confusing diff and a window in which link typos compile. It is cheap to leave alone today and gets more expensive as pages accumulate.
This is not caused by any recent change. It reproduces on
1933ee2, before the design work. It is filed now becauseapps/web/README.mdwas recently updated and points readers at that script, which makes it likelier to be run.Evidence.
apps/web/package.jsondefinesgenerate-routesas thetsr generateCLI. The Vite plugin that runs during a build is configured separately inapps/web/vite.config.ts. The trailing block inapps/web/src/routeTree.gen.tsis adeclare module '@tanstack/react-router'augmentation that registers the route tree; only the build's configuration produces it. The file is tracked — confirmed withgit ls-files.Suggested verification. From a clean checkout:
bun run generate-routes, thengit diff apps/web/src/routeTree.gen.ts. The nine-line block at the end of the file disappears. Thenbun run buildand diff again — it returns.Likely fix: either give the standalone script the same configuration the build plugin uses, or drop the script and document the build as the only way to regenerate. Deciding between them is a small architectural call about whether a standalone regeneration step should exist at all.
Surfaced by the verification pass on #15. See #15.