feat(static-assets): cache-bust JS/CSS via ?v=<commit-sha>, immutable in prod
All checks were successful
All checks were successful
Adds a `static_v(request, name, path=...)` Jinja helper that appends
?v=<commit-sha> from app.core.build_info, plus a CachedStaticFiles
subclass that serves Cache-Control: public, max-age=31536000, immutable
in production and no-cache in development. Browsers refetch JS/CSS
automatically on every deploy without the user having to hard-reload.
- New: app/core/static_files.py (CachedStaticFiles)
- Updated: app/templates_config.py (static_v helper)
- Updated: main.py (use CachedStaticFiles for *_static mounts)
- Codemod: 143 url_for('*_static', path='*.js'|'*.css') → static_v(...)
across 123 templates. Images/fonts/JSON locales intentionally
unchanged (out of scope).
- Arch rule: FE-024 (warning) flags raw url_for on JS/CSS to prevent
drift. Note: FE-008 was already taken by the number_stepper rule.
- docs/proposals/static-asset-cache-busting.md marked Done.
Closes plan from docs/proposals/static-asset-cache-busting.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,9 +1,18 @@
|
||||
# Static Asset Cache-Busting Plan
|
||||
|
||||
**Date:** 2026-05-17
|
||||
**Status:** Proposed
|
||||
**Implemented:** 2026-05-18
|
||||
**Status:** Done
|
||||
**Motivation:** Users must hard-reload after every release to pick up new JS/CSS. We need versioned asset URLs that flip automatically on deploy so browsers refetch without manual intervention.
|
||||
|
||||
## Implementation summary
|
||||
|
||||
- `static_v(request, name, *, path)` Jinja global in `app/templates_config.py` — appends `?v=<commit-sha>` from `build_info`.
|
||||
- `CachedStaticFiles` in `app/core/static_files.py` — subclass of `fastapi.staticfiles.StaticFiles` that sets `Cache-Control: public, max-age=31536000, immutable` in production and `no-cache` in development. Wired into the JS/CSS-bearing mounts in `main.py` (module statics + `/static`). Uploads and module locales keep default headers.
|
||||
- Codemod migrated 143 `url_for('*_static', path='*.js'|'*.css')` callsites across 123 templates to `static_v(...)`.
|
||||
- Architecture rule `FE-024` (warning) flags raw `url_for(...)` on JS/CSS so the pattern can't drift back. (Renamed from the proposed `FE-008`, which was already taken by the `number_stepper` rule.)
|
||||
- Verified: `mkdocs build --strict` clean, `validate-architecture` reports no new findings, smoke test renders `?v=<sha>`.
|
||||
|
||||
---
|
||||
|
||||
## Existing Infrastructure (Already in Place)
|
||||
|
||||
Reference in New Issue
Block a user