Skip to content

docs: correct web/README render model, asset pipeline, and structure#196

Open
Jose-Gael-Cruz-Lopez wants to merge 6 commits into
mainfrom
docs/web-readme-render-model
Open

docs: correct web/README render model, asset pipeline, and structure#196
Jose-Gael-Cruz-Lopez wants to merge 6 commits into
mainfrom
docs/web-readme-render-model

Conversation

@Jose-Gael-Cruz-Lopez

Copy link
Copy Markdown
Collaborator

Closes #50

Summary

Picks up the four items left on #50 after criteria 1 and 2 were met, and adds drift that postdates the issue.

Every claim below was checked against the code, not assumed.

What was wrong

1. It documented a route that was deleted. app/repo-assets/[...path]/route.ts was removed by the #43 fix, but the README described it in three places. Verified gone:

$ ls web/app/repo-assets
ls: web/app/repo-assets: No such file or directory

Replaced with the real pipeline: scripts/copy-repo-assets.mjspublic/repo-assets/ → static serving, run automatically by predev and build.

2. It asserted the opposite of the render model. The README said data is baked in at build time and "changes to those files require a new deploy/build to appear on the site". Every data-backed page has exported revalidate = 3600 since the #47 fix:

$ grep -rn 'export const revalidate' web/app/
web/app/page.tsx:6:export const revalidate = 3600
web/app/globe/page.tsx:6:export const revalidate = 3600
web/app/deck/page.tsx:6:export const revalidate = 3600
web/app/my/page.tsx:6:export const revalidate = 3600
web/app/hackathons/page.tsx:7:export const revalidate = 3600

The route table now matches what next build prints — five ISR routes at 1h, /resources with no revalidation, /auth/[[...auth]] dynamic. The same false rebuild claim appeared again under Production build; fixed there too.

3. /resources was absent entirely. It shipped in #154 and appeared in none of the page list, data-source table, or tree. It is the one page backed by neither loader — its content is constants in lib/resources.ts.

4. The nav notes were a breakpoint behind. #154 moved the inline links from sm to md (adding RESOURCES made the pill wrap between 640–673px), so "inline links at sm and up" and "below 640px" both described the old layout.

5. The scripts table listed four of six. npm test — the 94-test suite CI gates on — was missing, so a contributor reading only this file had no way to run it before pushing.

Verification

  • Every file path named in the README resolves on disk (checked programmatically, including the tree entries)
  • Route modes taken verbatim from a fresh npm run build
  • vitest 94/94 still passes; only web/README.md is touched, so nothing else can regress

Test plan

  • Read Render model against next build output — the three route rows should match
  • Follow Getting started from a clean clone; the globe and /resources should both come up

🤖 Generated with Claude Code

Jose-Gael-Cruz-Lopez and others added 6 commits July 22, 2026 02:42
…line

`app/repo-assets/[...path]/route.ts` was removed by the fix for #43, but the
README still described it in three places. A contributor following it went
looking for a file that does not exist.

Assets are copied by `scripts/copy-repo-assets.mjs` into `public/repo-assets/`
and served statically. Both `predev` and `build` run that script, which is why
it works without anyone invoking it — worth saying out loud, since the
directory is generated and not committed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The README asserted the opposite of what the code does: that data is baked in
at build time and "changes to those files require a new deploy/build to appear
on the site". Every data-backed page has exported `revalidate = 3600` since the
#47 fix, precisely so deadline-derived state recomputes without a rebuild.

Replaces the flat "Static (prerendered)" row with what `next build` actually
reports: five ISR routes at 1h, /resources prerendered with no revalidation
because its content is compiled-in constants, and /auth dynamic.

Also records *why* the hour exists, so the next person does not "simplify" it
away — #47's rationale lived only in next.config.ts comments.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
/resources shipped in #154 and the README never mentioned it — not in the page
list, the data-source table, or the tree. It is the one page backed by neither
loader: its content is constants in lib/resources.ts.

The nav notes were also a breakpoint behind. #154 moved the inline links from
`sm` to `md` because adding RESOURCES made the pill wrap between 640 and 673px,
so "inline links at sm and up" and "below 640px" both describe the old layout.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Same defect as the Render model section, one heading down: it told readers a
rebuild is required for data changes. It is not — the pages revalidate hourly.
Calls out /resources as the exception, since it has no revalidate.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
package.json defines six scripts; the table listed four. `npm test` is the
notable omission — it is the 94-test Vitest suite CI gates on, so a contributor
reading only this file had no way to run it before pushing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Correcting my own over-correction earlier in this branch. The README used to
claim every data change needs a rebuild; I replaced that with "a data change
does not need a rebuild to appear", which is wrong in the other direction.

next.config.ts bundles README.md, listings.json and geocodes.json into the
deployment via outputFileTracingIncludes, so a revalidation re-reads the
*deployed* copy. Editing those files still requires a new build and deploy.

What the hour genuinely buys is what #47 asked for and what the page comments
say: deadline-derived state — closing-soon flags and day counts, all computed
from the current date — stays correct between deploys.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Jose-Gael-Cruz-Lopez

Copy link
Copy Markdown
Collaborator Author

Pushed a correction to my own change on this branch — worth flagging rather than burying.

The original README claimed every data change needs a rebuild. I replaced that with "a data change does not need a rebuild to appear", which is wrong in the opposite direction.

next.config.ts bundles README.md, listings.json and geocodes.json into the deployment via outputFileTracingIncludes, so an ISR revalidation re-reads the deployed copy — not whatever is on main. Editing those files still requires a new build and deploy.

What the hour actually buys is what #47 asked for, and what the page comments say: deadline-derived state — closing-soon flags and day counts, computed from the current date — stays correct between deploys.

The Render model section now splits this explicitly, and the Production build section says to rebuild.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Low] Documentation: web/README render model is inaccurate + undocumented env vars (no .env.example)

1 participant