Skip to content

fix(docs): merge batch assets in combine job to fix client-side routing 404#264

Merged
ronaldtse merged 1 commit into
v5from
fix/docs-batch-assets-merge
Jun 18, 2026
Merged

fix(docs): merge batch assets in combine job to fix client-side routing 404#264
ronaldtse merged 1 commit into
v5from
fix/docs-batch-assets-merge

Conversation

@ronaldtse

Copy link
Copy Markdown
Contributor

Problem

Clicking a formula on /browse/ changed the URL but showed 404. Refreshing the page loaded it correctly. Classic client-side routing failure.

Root cause

VitePress produces different content-hashed JS chunks per build when the page set differs. Each build-batch job runs its own vitepress build, so 9 batches produce 9 distinct app.HASH.js files. The combine job was deploying dist-main's assets/ directory only — but browse HTML from each batch references batch-specific hashes that weren't in the deployed assets.

Verified by downloading artifacts from the latest deploy (run 27699130632):

Artifact app.HASH.js hash
dist-main CUFvjMGd
dist-batch-0 tggRrD32
dist-batch-1 lhlnUi-u
dist-batch-2 wADyZrW9
dist-batch-3 NxYOTzkh
dist-batch-4 TU-EUwTC
dist-batch-5 j-JEY3xz
dist-batch-6 Bh3mvEjZ
dist-batch-7 Sac3zhiF
dist-batch-8 BldWXoD6

None matched. Browse HTML from batch-N references batch-N's hash, which wasn't deployed → client-side navigation 404s on the missing chunk. The SSR HTML was correct (which is why refresh worked, masking the bug).

Fix

In docs.yml's combine job, also cp -r each batch's assets/ into dist/assets/. Content-hashing guarantees no filename conflicts (same content → same filename, different content → different filename). Total added payload is ~9 small duplicate-ish app.HASH.js chunks (~few KB each), acceptable for a static site.

Verification

After merge and deploy:

  1. Go to https://www.fontist.org/formulas/browse/
  2. Click any formula — should load directly (no 404, no refresh needed)
  3. Confirm in browser DevTools that /formulas/assets/app.<HASH>.js returns 200 (was 404)

Why this was masked

…ng 404

Symptom: clicking a formula on /browse/ changed the URL but showed 404; refreshing the page loaded it correctly. This is classic client-side routing failure — Vue Router fetches the route's JS chunk, the chunk 404s, the route can't render.

Root cause: each build-batch job in docs.yml runs a separate VitePress build, and VitePress produces different content-hashed JS chunks per build because the page set differs (9 batches → 9 distinct app.HASH.js files, plus dist-main's own hash). The combine job only deployed dist-main's assets/, but browse HTML from each batch references batch-specific asset hashes — so every batch's browse pages referenced chunks that weren't deployed.

Verified by downloading artifacts from run 27699130632: dist-main had app.CUFvjMGd.js, batches 0-8 had 9 different hashes (tggRrD32, lhlnUi-u, wADyZrW9, NxYOTzkh, TU-EUwTC, j-JEY3xz, Bh3mvEjZ, Sac3zhiF, BldWXoD6). None matched.

Fix: also cp -r each batch's assets/ into dist/assets/ during the combine step. Content-hashing guarantees no filename conflicts (same content → same filename; different content → different filename). Total added payload is ~9 small duplicate-ish app chunks (~few KB each), acceptable for a static site.
@ronaldtse ronaldtse merged commit c4aa9a2 into v5 Jun 18, 2026
9 checks passed
@ronaldtse ronaldtse deleted the fix/docs-batch-assets-merge branch June 18, 2026 01:28
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.

1 participant