Edge Side Includes

Edge Side Includes lets Varnish, Fastly, Akamai and other ESI-capable proxies assemble Drupal pages at the edge. It adds an ESI placeholder strategy to Drupal's render system: the personalized or uncacheable parts of a page become <esi:include> tags, the page shell is cached at the edge, and only the dynamic fragments are requested from Drupal.

BigPipe makes uncached pages feel faster by streaming them from PHP. This module makes more of each page cacheable, so far fewer requests reach PHP at all, including requests from authenticated users.

Features

  
• ESI placeholder strategy: Plugs into core's placeholder strategy chain alongside BigPipe. Any lazy builder placeholder, including those created by auto-placeholdering, can be served as an ESI fragment.

  

• Automatic fallback: ESI tags are emitted only when the proxy advertises support with the Surrogate-Capability request header. Otherwise rendering falls through to BigPipe or single flush, so local and non-ESI environments keep working.

  

• Per-fragment edge caching: Each fragment response gets its own Surrogate-Control max-age, derived from that fragment's render cache metadata.

  

• Role-aware fragments: A user context hash endpoint (the pattern used by FOSHttpCache) lets the edge cache role-varying fragments once per role instead of once per user.

  

• Tag-based invalidation: Fragment responses carry their cache tags in a configurable header (Cache-Tags, Surrogate-Key or Edge-Cache-Tag), so Purge invalidates exactly the fragments that depend on a changed entity.

  

• Signed fragment URLs: Fragment URLs are HMAC-signed with the site's hash salt, so clients cannot invoke arbitrary lazy builders or tamper with their arguments.

  

• Fine-grained control: Opt placeholders in or out by lazy builder callback, cache context or route.

  

• Debug mode: Optional HTML comments and response headers show each fragment's cache key, max-age and tags.

Post-Installation

  
1. Enable the module.

  

2. Configure your proxy to advertise ESI support and process ESI responses. For Varnish:

   sub vcl_recv {
     set req.http.Surrogate-Capability = "abc=ESI/1.0";
   }
   
   sub vcl_backend_response {
     if (beresp.http.Surrogate-Control ~ "ESI/1.0") {
       unset beresp.http.Surrogate-Control;
       set beresp.do_esi = true;
     }
   }
   

     Full example configurations, including the user context hash setup, are in the module's examples/ directory.

  

3. Go to Administration » Configuration » Development » Edge Side Includes to choose which placeholders become fragments, set the cache tags header name and toggle debug mode.

  

4. Load a page and check the debug headers to confirm fragments are being assembled at the edge.

Additional Requirements

  
• Drupal 10.3 or 11.

  

• An ESI-capable reverse proxy or CDN, such as Varnish, Fastly or Akamai with ESI enabled.

Recommended modules/libraries

  
• Purge, together with a purger for your edge (Varnish, Fastly or Akamai), for tag-based fragment invalidation.

  

• BigPipe (core), as the fallback strategy when ESI is unavailable.

Similar projects

  
• BigPipe (core): Streams placeholders from PHP to improve perceived performance, but every request still hits Drupal. The two are complementary, and BigPipe serves as this module's fallback.

  

• Purge: Invalidates content at the edge but doesn't change how pages are assembled. This module works with Purge rather than replacing it.

Known limitations

  
• ESI responses aren't streamed: the edge fetches all fragments before sending the page, so one slow fragment delays the whole response. Open-source Varnish Cache fetches fragments sequentially.

  

• Each uncached fragment is a separate Drupal request, so pages with many per-user fragments may be faster with BigPipe alone.

  

• The edge must forward session cookies on fragment subrequests for authenticated fragments to work.

Community Documentation

Documentation and example proxy configurations: [TBD]