Tiered cache-policy ENV vars per asset type

[sylvesterdamgaard]

Motivation

Today the image exposes a single NGINX_STATIC_EXPIRES (and matching NGINX_STATIC_CACHE_CONTROL) that applies to all static assets. In practice, sensible defaults differ per asset type:

Asset type	Sensible default	Why
Fonts (woff2/woff/ttf)	1y	Almost never changes once shipped
Images (png/jpg/svg/webp/avif)	30–90d	Changes occasionally
CSS/JS	30d–1y with immutable if filename-versioned	Vite/Webpack hash filenames; safe for long expiry
HTML	0 / no-cache	Always re-fetch the entry document

A single knob forces users to either over-cache HTML (stale content) or under-cache fonts (wasted bandwidth).

Proposal

Replace the single NGINX_STATIC_EXPIRES with tiered env vars (keep the old one as an alias / fallback for back-compat):

NGINX_CACHE_FONTS_EXPIRES=1y
NGINX_CACHE_IMAGES_EXPIRES=30d
NGINX_CACHE_CSS_JS_EXPIRES=30d
NGINX_CACHE_HTML_EXPIRES=0          # or "no-cache"
NGINX_CACHE_IMMUTABLE=true          # appends `immutable` to Cache-Control on CSS/JS/fonts/images

Generate separate location blocks for each tier in the default template.

Acceptance criteria

• Per-tier env vars implemented
• NGINX_CACHE_IMMUTABLE toggles the immutable directive in the long-lived tiers
• Old NGINX_STATIC_EXPIRES continues to work (treated as fallback for unset tiers)
• Documented in env vars reference with rationale per tier