Skip to content

Templates: Version the theme stylesheet so updates bypass the browser cache - #71

Merged
whereareiam merged 1 commit into
devfrom
fix/theme-stylesheet-cache-busting
Oct 3, 2026
Merged

whereareiam merged 1 commit into
devfrom
fix/theme-stylesheet-cache-busting

Conversation

@whereareiam

Copy link
Copy Markdown
Owner

After a theme update, pages rendered with the new templates but the previous theme stylesheet until the browser cache expired. #64 versioned the scripts and component stylesheets the templates link; this closes the gap it left for the main theme-*.css files.

Cause

Forgejo links the selected theme as theme-<name>.css?v=<Forgejo version> and serves it with Cache-Control: max-age=21600. A theme update does not change Forgejo's version, so the URL stays the same and browsers keep the cached file for up to six hours. The auto themes add a second layer: they @import their light and dark files by a fixed path.

Seen after deploying #70: the pull request list showed its new heading row and counters with the old layout rules (button beside the heading, icons on Open/Closed, old filter order).

Changes

  • base/head_style.tmpl: the theme overrides Forgejo's two-line partial. It is identical except that the build appends a version of all theme files to the theme link: ?v={{AssetVersion}}-<theme version>. Forgejo's own index.css link is unchanged.
  • Auto themes: each @import in theme-*-auto.css gets the content version of the file it loads. This is done in dist, so the release archives carry it too.
  • Asset stamping: links that already carry a version are skipped, so the new partial's index.css link is left alone.

Limits

  • Installations that use only the CSS archives and not the templates keep Forgejo's own link. The versioned imports still help them once the auto file itself is refetched.
  • The first update that introduces this partial is still affected once, because the cached page links come from the previous build.
  • The partial copies two lines of Forgejo 16.0.3's template; it has to be rechecked when Forgejo changes that file.

Checks

  • bun commit checks pass (403 tests), including a new test that the theme link and every auto-theme import carry the version of the files they load. Running the assemble step twice gives the same output.
  • Dev preview (Forgejo 16.0.3): pages link theme-github-auto.css?v=16.0.3~gitea-1.22.0-<version>, the stylesheet and its versioned imports load, no template errors are logged, and the pull request list renders as before.

ref #64

🤖 Generated with Claude Code

… cache

Template scripts and component stylesheets are already linked by
content version, but the theme's main stylesheet was not. Forgejo links
it with its own release as the only version and lets browsers cache it
for six hours, so after a theme update the new markup rendered with the
previous stylesheet until the cache expired or the page was reloaded
without it.

The theme now overrides Forgejo's two-line head_style partial. It is
identical except that the build appends a version of all theme files to
the theme link. The auto themes import their light and dark files by a
fixed path, so each of those imports gets the version of the file it
loads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@whereareiam whereareiam added the bug Something isn't working label Oct 3, 2026
@whereareiam
whereareiam merged commit cf401ff into dev Oct 3, 2026
8 of 9 checks passed
@whereareiam
whereareiam deleted the fix/theme-stylesheet-cache-busting branch October 3, 2026 16:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant