In production a template edit keeps rendering the old output while development shows it immediately — what explains the difference?

Template rendering is two phases with very different costs, and the cache between them explains most of the surprising behaviour teams hit in production. ## What is actually cached The engine turns template **source** into an **executable form** — a parse tree, a generated function, a compiled unit, depending on the engine — and keeps that form in memory under a key. The key is normally the resolved template name plus whatever dimensions took part in resolution: locale, theme, variant. What is *not* cached, in the ordinary configuration, is the rendered output: each request still executes the template against its own model. This matters for reasoning about failures. A stale **page** and a stale **template** are different problems with different fixes — an output cache in front of the application, versus a compiled-template entry inside it. ## Why development and production diverge | Setting | Development | Production | |---|---|---| | Compiled-template cache | off, or validated against the source each render | on for the process lifetime | | Source of templates | files on disk, edited in place | usually files inside the deployed artifact | | First-request cost | paid constantly, and unnoticed | paid once per template, visible after deploy | | Refresh path | save the file | redeploy or restart the process | So two mechanisms, not one, produce "my edit did nothing": the cache holds an already-compiled entry, and in a packaged deployment the file you edited may not even be the file the process reads. Both are intentional. A per-render source check costs a metadata lookup on every render of every template, which is exactly the kind of small constant you do not want in a hot path serving many requests. ## The production effects that follow - **Cold-start latency.** The first request to touch each template pays compilation. After a deploy, a scale-out, or a process restart, a burst of requests hits an empty cache at once, so the tail latency spike is concentrated rather than spread. Precompiling templates at build time, or warming the important ones at startup before the instance accepts traffic, removes it. - **Rolling deploys serve two versions.** The cache is per process. During a rollout some instances hold the old compiled form and some the new, so a user can see both within seconds. This is normally fine, and is worth remembering when a template change ships alongside a model change that the old template cannot render. - **Unbounded growth from dynamic names.** A cache keyed by a name derived from request input grows with the input space. Beyond the memory problem, a name built from untrusted input lets a caller aim resolution at templates you never intended to expose. Map request values onto a fixed allow-list of names. - **Negative lookups.** Whether a *failed* resolution is remembered varies. If misses are not cached, every request for a name that does not resolve walks the whole resolver chain and touches the filesystem, which turns a broken link into a measurable load source. - **Variant multiplication.** Keys that include locale and theme multiply entries by the number of supported combinations. It is rarely a problem, but it is the reason a "small" template set can hold thousands of compiled entries. ## Diagnosing it in the field 1. **Establish which layer is stale.** Request the page with caching intermediaries bypassed. If the old content survives that, the staleness is inside the application; if it disappears, an output cache or a reverse proxy owns it. 2. **Confirm what the process is reading.** Check whether the deployed artifact contains the edited template at all. Editing an extracted copy beside a running process is a common false lead. 3. **Check the profile.** Confirm whether the cache is enabled and whether source re-checking is configured, and confirm which profile the instance actually booted with rather than which one the repository defaults to. 4. **Restart deliberately.** A restart that fixes it confirms the compiled-template cache; a restart that does not sends you back to step one. ## The judgment call The cache is not a setting to "fix" — disabling it in production trades a per-render metadata check and repeated compilation for an editing convenience nobody has in a packaged deployment. The two legitimate moves are to **precompile at build time**, which converts the cost into build time and removes the cold-start spike entirely, and to **warm on startup**, which keeps runtime compilation but moves it before the instance takes traffic. Hot-reloading templates in production is a third option, occasionally chosen so content can change without a deploy; it means accepting a source check or an explicit invalidation path, and treating templates as deployable content with their own review trail.