Edge Side Includes (ESI)

ESI lets you cache pages that contain dynamic content by separating the static template from the personalized parts.

The Problem

A product page could be cached for hours, but the shopping cart count in the header changes constantly. Without ESI, the entire page becomes uncacheable because of one small dynamic element.

How It Works

Your origin returns a page with ESI placeholder tags. Edgelin caches this template and fetches the fragments separately when serving the page. Each fragment can have its own cache duration—the cart widget fetches fresh every time while the footer caches for hours.

<header>
  <esi:include src="/fragments/cart-widget"/>
</header>
<main>
  Static product content...
</main>

Implementation

Create endpoints that return only the fragment HTML (not a full page), then reference them with <esi:include> tags in your template. Control caching with standard HTTP headers on your fragment endpoints:

• Cache-Control: no-cache — always fetch fresh

• Cache-Control: max-age=60 — cache for 60 seconds

Supported Tags

• <esi:include src="/path"/> — insert fragment content

• <esi:remove>...</esi:remove> — fallback content, removed during ESI processing

Limitations

• Fragments must be same-domain paths

• No nested ESI tags in fragments

• 3 second timeout per fragment

• 1MB maximum fragment size