perf: netlify - Improve asset caching and baseline headers #6

Performance Optimisation Summary

Improve hashed-asset caching and baseline security headers without changing HTML revalidation or breaking integrations.

Rebase required before status audit

PR #345 currently targets main; historical branch ancestry has not been verified. Rebasing the implementation branch onto current develop and retargeting the PR to develop remain pending. Preserve the intended changes while resolving conflicts.

After rebasing, audit the resulting diff, rerun relevant tests/build/checks, and reassess acceptance criteria, DoR and DoD against fresh evidence. Existing commits and the earlier preview do not establish compatibility with develop or completion.

The previous rebase attempt was blocked by unavailable coding credits; it made no branch changes.

Linked Stories/Tasks/PRs/Epic

Coordinate root configuration changes with #3.

Reviewed implementation: #345, commit 5d8d98f7041ae0ae33fe2920f2fc64b74121f3f9, remains open and unmerged, targeting main. #343 is open and unmerged, with ten commits and six changed files at head f33840c, targeting develop. Its latest Jest head/base and comparison checks passed, but labelling and changelog validation failed; CI is not fully green. Nine of ten review threads are resolved, with one outdated thread still open; review approval and deployment verification remain pending. PR #343 overlaps this work; the intended relationship remains unresolved. Neither reference asserts completion or a closing relationship. No epic supplied.

Milestones & Timeline

Estimate L. No milestone or deadline requested.

Describe the performance issue

The audit reports HTML and hashed assets both use max-age=0,must-revalidate, with only Netlify’s default HSTS security header present. No Lighthouse benchmark measured.

Steps to reproduce the issue

Inspect response headers for HTML and hashed assets; independently confirm the audit findings.

Expected behavior

Verified hashed assets use one-year immutable caching; HTML retains revalidation. Baseline headers are compatible with application requirements.

Screenshots or logs

Supplied audit.

Environment

React/Vite frontend on Netlify; WordPress/PHP not applicable.

Acceptance Criteria

• Deployed hashed assets receive one-year immutable caching; unhashed files and HTML do not.
• HTML revalidation and direct navigation/refresh work for nested routes.
• Deployed baseline security headers match the intended configuration without breaking integrations.
• Typeform, YouTube, Vimeo and Google Fonts pass browser checks.
• A subsequent deployment loads new hashed assets without stale-content errors.
• No CSP introduced in the new root configuration.
• Before/after header evidence recorded; no unmeasured performance gains claimed.

Additional Context

Reported evidence, not independently verified here. Audit made no changes and performed no browser, accessibility or Lighthouse testing.

Definition of Ready (DoR)

• Intended outcome, reproduction procedure and cache targets documented.
• Audit reference supplied.
• Acceptance criteria defined.
• Estimate L recorded.
• Relationship with overlapping PR perf: netlify - Add HTML revalidation and cache verification and routing work resolved.
• Implementation branch rebased onto the latest origin/develop and PR retargeted to develop; changing the target alone does not satisfy the rebase requirement.
• Status audited again after rebasing against the resulting head/base commits, updated diff, fresh CI, code review and Deploy Preview.

Definition of Done (DoD)

• Root configuration, cache generator and Vite integration committed.
• Unit tests and deployed-header checker added.
• Changelog entries committed.
• Deploy Preview available for reviewed commit.
• Passing unit-test execution independently evidenced.
• Actual Node version, effective configuration and generated headers verified from the build.
• All deployed acceptance checks demonstrated.
• Stale “no test runner” documentation corrected.
• Code review approved and applicable checks reviewed.
• Agreed PR merged and production behaviour verified.

Implementation guide

1. Confirm the active deployment configuration

• Inspect src/app/netlify.toml and Netlify’s configured base directory/configuration path.
• Confirm the build command and publish directory. The file specifies pnpm run build and dist; package.json defines build as vite build.
• Coordinate configuration and redirect changes with bug: netlify - Fix unreadable redirects output and validate routing #3. Do not move configuration files without confirming deployment requirements.

2. Apply caching only to verified hashed assets

• Build successfully and inspect dist to establish which filenames contain content hashes.
• Review the existing /assets/* immutable rule; narrow it if that directory includes unhashed files.
• Use Cache-Control: public, max-age=31536000, immutable only for verified hashed assets.
• Preserve HTML max-age=0, must-revalidate, including responses served through SPA routes.

3. Review baseline security headers

• The nested configuration already declares nosniff, a referrer policy, framing restrictions, Permissions Policy and CSP.
• Review framing and feature restrictions against application requirements before enabling them.
• Defer new CSP work. Establish whether the existing CSP is active before proposing any removal or change.

4. Verify a deployed preview

• Capture before/after headers using curl -I for /, a nested application route and an actual hashed asset.
• Check HTML revalidation, immutable asset caching and correct loading after a subsequent deployment.
• Exercise Typeform, YouTube, Vimeo and Google Fonts; inspect browser console/network errors.
• Record results in the PR without claiming unmeasured performance gains.

Unresolved verification

Required before merge: rebase the implementation branch onto the latest origin/develop, reconcile integration differences and retarget the PR to develop. Do not merge before the rebase and subsequent status audit. Previous successful checks apply to the pre-rebase commit and do not establish readiness afterwards.

Read-only audit on 19 October 2026 confirmed committed root Netlify configuration, exact-path hashed-asset caching, Vite integration, baseline security headers, SPA fallback routing, seven test cases, a deployed-header checker and documentation/changelog updates at 5d8d98f7041ae0ae33fe2920f2fc64b74121f3f9. No tests or deployment validation were run during this audit. After rebasing, inspect the updated diff, reconcile overlapping work, obtain fresh CI and code review, and validate the new Deploy Preview before reassessing readiness. CodeRabbit's latest comment reports a missing review seat; its successful “review skipped” status is not approval.

Implementation is committed in PR #345 at 5d8d98f7041ae0ae33fe2920f2fc64b74121f3f9; its Deploy Preview is available. The commit adds root Netlify configuration using npm and Node 24; the nested configuration is marked inactive under the implementation agent's reported site settings. Earlier pnpm setup failures are historical context, not evidence that this preview failed to build.

Functional verification remains outstanding: actual Node version/effective configuration, generated header contents, deployed response headers, browser integrations and cache behaviour across subsequent deployments. The implementation agent reported 7/7 unit tests passing; this was not independently rerun. Contributor documentation still contains stale “no test runner” statements. Resolve overlap with PR #343 and the actual agent branch targeting main versus the repository's perf/develop conventions before completion. No measured performance gain or production verification is claimed. The implementation guide above retains the original investigation context; it is not a statement that those steps are complete.

Branch instructions

• Repository: lightspeedwp/ThisOneTimeOnAcidCom.
• Implementing target: this caching/header issue, synced with GitHub issue 6. No parent epic identified.
• Allowed closing targets: none newly established. Review the historical closing-reference risk disclosed in the competing contribution before merge; no history or association changes authorised.
• Branch state: unresolved; neither branch recommended for reuse pending overlap and integration decisions.
• Branch: perf: netlify - Improve hashed-asset caching and security headers #345 uses agent-6ad494753597937a10a0525f, head 5d8d98f7041ae0ae33fe2920f2fc64b74121f3f9. perf: netlify - Add HTML revalidation and cache verification #343 uses perf/netlify-asset-caching-headers, head bbb9e50d41deea89a83590f5528e380b66463dbf, currently 14 commits/nine files.
• Base: required integration base develop, checked at 4ecdb26d9655a48bf000a7c89da2f70383edce87. PR 345 still targets main at cb53d2c4cdf35a69fc322644e3c22f608d7f03f2; PR 343 targets develop. Historical ancestry remains unverified. No retargeting/rebase performed or authorised.
• Naming policy: local guide/validator at checked develop and organisation strategy at 8f28eca80bff198879f7aaf496717dc0551bb32e; perf/ fits caching. The actual agent branch does not follow the checked pattern; do not rename automatically.
• PR template: unresolved routing conflict. Local routing suggests absent pr_performance.md; the organisation map specifies pr_feature.md. Preserve Performance classification pending a decision.
• Missing evidence: delivery contribution, integration compatibility, effective deployment settings and deployed acceptance; competing PR includes ancillary comparator/CI/report-directory work.
• Constraints: no branch creation, reuse, rename, rebase, retargeting, force-push, association change, merge or deployment.

Expected file changes

Provisional integration plan, not wholesale approval of either PR. Existing paths below verified at reviewed PR 345 head 5d8d98f7041ae0ae33fe2920f2fc64b74121f3f9.

No new paths, moves or deletions proposed. Runtime, documentation and protected changelog scope require separate bounded previews. Exclude CSP, generated-output edits, integration changes, centrally managed workflows and ancillary comparator/report-directory work. Fresh build/regression evidence, deployed headers, browser compatibility and subsequent-deployment acceptance remain required; none performed in this audit. Stop for revised scope before materially different operations.

Unanswered clarification questions

These questions clarify the existing performance scope and acceptance evidence; they do not authorise merging, deployment or additional implementation.

1. What is the agreed relationship and non-overlapping scope between PR perf: netlify - Add HTML revalidation and cache verification #343 and PR perf: netlify - Improve hashed-asset caching and security headers #345?
2. Which branch, base and head revision should be assessed for integration readiness?
3. Which fresh checks and authorised review evidence are required for that revision?
4. What deployed evidence should verify cache headers, nested-route revalidation, integrations and post-deployment asset loading?
5. Who accepts the deployed results and determines whether any remaining failures prevent closure?