Edge Side Includes (ESI)

What is ESI?

Edge Side Includes (ESI) is a small markup language that lets a CDN or reverse proxy assemble a web page at the edge from multiple independently-cached fragments. Instead of caching a whole page as one unit (all-or-nothing), ESI lets you break a page into pieces — a mostly-static shell plus a few dynamic fragments — and cache each piece with its own policy. The edge stitches them together per request: it serves the aggressively-cached static parts instantly from the edge cache and only fetches or generates the small dynamic fragments that actually change. An ESI tag like <esi:include src="/user-greeting"/> tells the edge “fetch this fragment and splice it in here.”

The problem it solves — partial caching of mixed pages

ESI addresses a real tension: many pages are mostly static with small dynamic bits. Consider a product page — the layout, header, footer, images, and description rarely change, but the “Hello, Sri” greeting, the cart count, and inventory status are per-user or frequently-updated. Caching the whole page is impossible (the dynamic bits would be wrong or leak between users); caching nothing wastes the opportunity to cache the 95% that’s static. ESI lets you have both: cache the static shell at the edge for a long TTL, and mark just the greeting and cart count as ESI includes that are fetched fresh (or cached briefly) per request. The edge assembles the final page, so you get near-static performance for the bulk of the page while keeping the dynamic parts correct. This “personalize at the edge without giving up caching” capability is genuinely useful for high-traffic sites where full-page caching isn’t possible but origin load must stay low.

The honest reality: powerful but niche and quirky

ESI is an old (early-2000s) standard, and the honest assessment is that it’s powerful for its specific use case but niche, inconsistently supported, and increasingly overtaken by newer approaches. The realities: support varies — it’s implemented by Varnish, some CDNs (Akamai originated it, Fastly and others support subsets), and reverse proxies, but the implementations differ in which parts of the spec they support, so ESI behavior isn’t uniformly portable across platforms. It adds complexity (another templating layer, harder debugging — a page is now assembled from fragments each with its own caching and failure behavior), and fragment failures need handling (what happens if a dynamic include’s origin is slow or down? ESI supports fallbacks/onerror, but you must design for it). Security matters: fragments must be scoped correctly, and a notable class of vulnerabilities (ESI injection) exists where unsanitized user input reaches an ESI processor and gets interpreted as ESI markup — so untrusted content must never be evaluated as ESI. And the modern context: much of what ESI did is now often handled by edge compute (Cloudflare Workers, Vercel Edge, Fastly Compute) that can assemble and personalize responses at the edge programmatically with more flexibility, by client-side composition (fetching dynamic fragments via JavaScript/APIs), or by framework-level partial caching. ESI remains relevant where it’s already deployed (Varnish/Akamai setups) and for straightforward fragment-caching needs, but it’s rarely the first reach for new architectures. The recurring mistakes: assuming ESI works identically across CDNs/proxies (it doesn’t), not handling fragment failures gracefully, and the security hole of letting untrusted input be processed as ESI markup.

What people get wrong

• Assuming portability — ESI implementations differ across Varnish, Akamai, Fastly, etc.; a setup that works on one may not behave the same on another.
• ESI injection: letting unsanitized user input reach the ESI processor lets attackers inject ESI markup — untrusted content must never be evaluated as ESI.
• Reaching for it in new architectures — edge compute and client-side composition now cover most of ESI’s use cases more flexibly; ESI fits existing Varnish/CDN setups more than greenfield.

Primary source: Fastly: Using ESI