🤖 Assets

rastrillo.Assets fingerprints your static files so they can be cached forever and still update on an ordinary reload.

assets := rastrillo.NewAssets(app.StaticFS)
mux.Handle("GET /static/", assets.Handler())

Path maps a file to a URL carrying its content hash, and Handler serves that URL with an immutable Cache-Control. Because the hash changes whenever the content does, your HTML always links a URL the browser has never cached stale. No cache-busting query string, no version constant to remember to bump.

The FS is served with http.FileServerFS semantics — URL path is / plus the FS path — which matches how the scaffold embeds static/. Mount at GET /static/ with no StripPrefix.

Delivered once, yours afterwards

Two files arrive in your static/ directory from rastrillo new rather than from an import: tokens.css (the design tokens) and rastrillo.js (the progressive-enhancement shim). The scaffolded icons package works the same way.

Edit them freely. Nothing in the framework will overwrite them, and no upgrade will change them under you.

The framework's files are served minified

Assets serves the files rastrillo new put in static/ (tokens.css, theme.css, shell.css and the framework's scripts) without their comments and extra whitespace, and gzipped for a browser that accepts it. A page downloads about a third of what the commented files weigh. No change to your app is needed.

Your copies in static/ keep their comments, so you can still read them. Path puts the hash of the bytes actually sent in the URL, so an edit to your copy still reaches every browser on the next load.

Your own files, and anything outside static/'s top level, are served exactly as written. If the minifier cannot read a framework file, such as a script you edited into invalid JavaScript, Assets serves it as written. It does not serve an empty file or an error.

The pin test

The scaffold ships a vendored_test.go asserting the delivered copies are byte-identical to the library's.

It is a tripwire, not a prohibition on editing. It tells you that you have drifted, so drift is something you chose rather than something you discover much later while debugging a component that no longer matches its stylesheet.

When you do mean to diverge, say so in the same commit as the edit: add the file's name to vendoredIsMine at the top of that test. A pin test everybody knows is failing protects nothing.

rastrillo doctor reads the same list, so a file you have recorded as yours is one it leaves alone too — and it will re-copy the ones you have not. See The CLI.

Read this page as markdown — exact, unstyled, and cheap for an agent to fetch.