Investigate unnecessary asset changes between deploys

[TitusKirch]

Before you start

• I searched existing issues and didn't find a duplicate

What problem are you trying to solve?

Deploys #2–#4 uploaded approximately 2,600 new or modified static assets each, including after a small anchor fix. Wrangler upload and publication took roughly 32–34 seconds. These counts alone do not establish which changes are avoidable.

Proposed solution

Compare two clean production builds of the same commit, then a build with a narrowly scoped content change. Group changed assets by type and identify their actual causes. Build IDs and embedded metadata are hypotheses to test, not established causes. Report which differences are required and which can safely be avoided. Validate any resulting improvement against upload duration, asset correctness and cache invalidation; a documented finding that no safe improvement is worthwhile also resolves the investigation.

Alternatives considered

Accept the existing upload cost. Never freeze identifiers or reuse stale HTML and payloads merely to reduce the changed-file count.

Additional context

Deploy #4 uploaded 2,627 files with 1,310 already present; asset transfer took 24.35 seconds and Wrangler upload/publication roughly 32 seconds.

Decided (refinement, 2026-09-11):

• The investigation may use controlled manual runs of the existing GitHub Actions Deploy workflow on main. CI owns the deployment credentials, so no direct Cloudflare access is required.
• Those runs may publish the compared builds. They cover two clean builds of the same commit and one narrowly scoped content change, and record the Wrangler upload/publication measurements required by this issue.
• Supersedes the unresolved production-measurement access question above.

[TitusKirch]

Findings — unnecessary asset changes between deploys

Method

Four clean Cloudflare-preset builds of www/ from one commit (f13d5ef, tip of dev), each preceded by removing www/.nuxt, www/.output, www/.data and both Vite caches — the state a CI checkout is in. Each build's .output/public was hashed file by file with SHA-256, which is what wrangler's asset upload compares: it sends a path→hash manifest and uploads only the hashes the account does not already hold.

Production numbers come from the existing Deploy run logs; no new deploys were triggered (reason at the bottom).

What a rebuild of the same commit changes

assets per build	1,414 (72.4 MB)
changed	807
added / removed	1 / 1 (_nuxt/builds/meta/<uuid>.json)
distinct new content hashes — what wrangler would upload	808 (57.1%)

Reproduced on every pair of the four builds: always 808, with zero source changes.

By type:

files	what	why
399	**/_payload.json	prerenderedAt
399	**/index.html	prerenderedAt inlined in __NUXT_DATA__, plus buildId in three places
8	__sitemap__/*.xml, sitemap_index.xml	sitemap credits comment
1	_nuxt/builds/latest.json	buildId + Date.now()
1	_nuxt/builds/meta/<uuid>.json	buildId is the filename

Byte-identical in every build, so not a source of churn — and two of the issue's hypotheses are refuted outright:

• all 281 OG images — satori/resvg render reproducibly;
• 227 of 228 _nuxt chunks, names and contents — the build id does not cascade into chunk hashes;
• all 37 Content SQL dumps and all 37 __nuxt_content files;
• the 10 committed devtools pages, the OG fonts, the static images.

The actual causes

1. payload.prerenderedAt — present in 798 of the 808 files. Nuxt's SSR renderer sets ssrContext.payload.prerenderedAt = Date.now() per rendered route. It lands in every _payload.json and, through the inlined __NUXT_DATA__, in every page. Nuxt reads it in exactly two places and only for truthiness (pages/runtime/plugins/router.js, app/composables/payload.js) — the number itself is never compared. There is no configuration option; it is hard-coded in the renderer.
2. buildId — 2 files of its own, 3 occurrences in every page. @nuxt/schema resolves it to randomUUID() for any non-dev, non-test build. It appears as ?_b= on the payload preload, as app.buildId in the inlined runtime config, and as data-src on __NUXT_DATA__. Overridable (buildId / NUXT_BUILD_ID).
3. @nuxtjs/sitemap credits comment — 8 files. v8.5.0 appends <!-- XML Sitemap generated by @nuxtjs/sitemap v8.5.0 at <ISO now> -->. Overridable with sitemap: { credits: false }.
4. Async-completion ordering — 19 to 30 files. Masking (1)–(3) and re-hashing makes two clean builds agree on 1,395 of 1,414 files. The rest differ for a fourth reason: things are serialised in the order their async work finished. Two instances found — the nuxtApp.payload.data keys (the @nuxt/icon server entries come out compass, list, ruler, gavel, rocket, book-open in one build and rocket, compass, book-open, list, ruler, gavel in the next), and the <xhtml:link hreflang> alternates inside each sitemap <url> (pt-PT, es-ES, fr-FR against es-ES, fr-FR, pt-PT). A small share of the churn, but a hard floor under reproducibility: fixing 1–3 alone would still not make two builds identical.

What it costs, in production

From the Deploy run logs (no new runs):

run	commit	trigger	assets read	new/modified	share	upload → publish
34536426271	7fa9937	push	5,709	2,829	49.6%	33.9 s
34546865349	23ded41	push	5,774	2,876	49.8%	32.6 s
34547264105	ebda61d	release	5,802	3,594	61.9%	39.4 s

Two unrelated commits landing within 0.2 points of each other is the signature of a floor, not of a diff: the upload is dominated by what changes anyway. The release build sits ~700 assets higher because it bumps the version shown on every page, which is genuine change.

The upload step is 33–39 s inside a job whose build step alone is 4–5 minutes. Removing the entire floor would save roughly 15 s per deploy — about 4% of the job. The cost worth more attention is the other axis this issue names: cache invalidation. Every prerendered page gets a new content hash on every deploy, so no edge or browser cache entry for any page survives a deploy that did not touch that page.

Required against avoidable

Between two builds of the same commit, none of the 808 is required. What each lever would actually buy, counted on its own rather than by how many files the value appears in — the 399 pages need prerenderedAt and buildId fixed, because either one alone still rewrites them:

lever	files it removes on its own	share	safe?
sitemap.credits: false	8	1.0%	yes — one supported option
freeze prerenderedAt	399 (the payloads)	49.4%	needs a layer server plugin overriding a Nuxt core field
pin buildId	2 (the build manifest)	0.2%	not here — see below
both of the two above	800 (payloads, pages, manifest)	99.0%	inherits both objections
ordering (cause 4)	19–30, overlapping every row above	—	not diagnosed to a fix

Why pinning buildId is wrong in this repo specifically. The obvious move is NUXT_BUILD_ID=$GITHUB_SHA. But deploy.yml fires on push to main and again when a release is published — the same commit, built twice, and the second build can legitimately differ because latest now resolves to the new tag. Two deploys sharing a build id would tell every client's app manifest that nothing had changed. A commit SHA is not a content identity for this site.

Why freezing prerenderedAt is not a free win either. It is technically reachable: a server plugin on app:rendered can set ssrContext.payload.prerenderedAt before the payload is serialised, and since both consumers only test truthiness any non-zero constant works. But this is a published layer — the plugin would rewrite a Nuxt core payload field in every site that extends duxt, for a field Nuxt may start reading the value of tomorrow. It is also precisely the "freeze identifiers … merely to reduce the changed-file count" this issue ruled out, and on its own it would still not produce a reproducible build while cause 4 stands.

Conclusion

No safe improvement is worthwhile today — which this issue names as a resolution. The only supported, zero-risk lever (sitemap.credits: false) is worth 1% of the churn and is invisible against a 33-second upload step; the lever worth 99% requires overriding Nuxt core from a published layer and would still leave the build non-reproducible.

The measurement is recorded in CLAUDE.md / AGENTS.md under Deployment — www/ on Cloudflare Workers, so it does not have to be re-derived.

If reproducible builds are later wanted as a property in their own right — which is the honest justification, not the file count — the order is: (a) fix cause 4 where the ordering is produced, (b) sitemap.credits: false, (c) ask Nuxt for a settable prerenderedAt rather than overriding it downstream, (d) only then revisit buildId, with the release double-build in mind.

Two things worth flagging separately

• A narrowly scoped content change cannot be injected locally. www/app/app.config.ts sources its docs as repo: 'kirchDev/duxt' with refs (tag: latest, tag: v0.2.0, branch: main, tag: v0.1.0), so Content fetches each ref and a working-tree edit under docs/ does not reach the build at all. Verified: a one-line edit left dump.docs.sql and the rendered page byte-identical, and produced the same 808-file churn as a no-op rebuild. That leg of the comparison can only be run by a real commit on a ref the site sources — which is why this issue authorised production runs.
• Why the authorised production runs were not spent. Per-file hashing of four local builds is a sharper instrument than a deploy log's aggregate count, and it isolated the causes down to the line of code. The production confirmation already exists in the runs above, and because no change was made there is nothing to validate against upload duration. The authorisation is unspent if the direct same-commit-redeploy confirmation is wanted; note that Cache rendered OG images between deploys #43 and Skip superseded builds before production deployment #46 are concurrently changing this pipeline, so measurement-only deploys now would muddy their evidence.

_{Prose-only change, so no tdd loop was driven — there is no code behind it. Verified with pnpm check.}