Need help with react-esi?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

593 Stars 27 Forks MIT License 41 Commits 11 Opened issues


React ESI: Blazing-fast Server-Side Rendering for React and Next.js

Services available


Need anything else?

Contributors list

# 2,443
17 commits
# 361,413
2 commits
# 189,009
2 commits
# 75,873
1 commit
# 437,394
1 commit

React ESI: Blazing-fast Server-Side Rendering for React and Next.js

Build Status Coverage Status npm version MIT Licence

React ESI is a super powerful cache library for vanilla React and Next.js applications, that can make highly dynamic applications as fast as static sites. It provides a straightforward way to boost your application's performance by storing fragments of server-side rendered pages in edge cache servers. It means that after the first rendering, fragments of your pages will be served in a few milliseconds by servers close to your end users! It's a very efficient way to improve the performance and the SEO of your websites; and to dramatically reduce both your hosting costs and the energy consumption of these applications. Help the planet, use React ESI!

Because it is built on top of the Edge Side Includes (ESI) W3C specification, React ESI natively supports most of the well-known cloud cache providers including Cloudflare Workers, Akamai and Fastly. Of course, React ESI also supports the open source Varnish cache server that you can use in your own infrastructure for free (configuration example).

Also, React ESI allows to specify a different Time To Live (TTL) per React component and to generate the corresponding HTML asynchronously using a secure (signed) URL. The cache server fetches and stores in the cache all the needed fragments (the HTML corresponding to every React component), builds the final page and sends it to the browser. React ESI also allows components to (re-)render client-side without any specific configuration.

ESI example

Schema from The Varnish Book

Discover React ESI in depth with this presentation



Using Yarn:

$ yarn add react-esi

Or using NPM:

$ npm install react-esi


React ESI provides a convenient Higher Order Component that will: * replace the wrapped component by an ESI tag server-side (don't worry React ESI also provides the tooling to generate the corresponding fragment); * render the wrapped component client-side, and feed it with the server-side computed props (if any).

React ESI automatically calls a

static async
method named
to populate the initial props of the component. Server-side, this method can access to the HTTP request and response, for instance, to set the
header, or some cache tags.

These props returned by

will also be injected in the server-side generated HTML (in a
Client-side the component will reuse the props coming from the server (the method will not be called a second time).
If the method hasn't been called server-side, then it will be called client-side the first time the component is mounted.

The Higher Order Component

// pages/index.js
import React from 'react';
import withESI from 'react-esi';
import MyFragment from 'components/MyFragment';

const MyFragmentESI = withESI(MyFragment, 'MyFragment'); // The second parameter is an unique ID identifying this fragment. // If you use different instances of the same component, use a different ID per instance.

const Index = () => (

React ESI demo app

// components/MyFragment.js
import React from 'react';

export default class MyFragment extends React.Component { render() { return (

A fragment that can have its own TTL

    <div>{this.props.greeting /* access to the props as usual */}</div>


static async getInitialProps({ props, req, res }) { return new Promise(resolve => { if (res) { // Set a TTL for this fragment res.set('Cache-Control', 's-maxage=60, max-age=30'); }

  // Simulate a delay (call to a remote service such as a web API)
    () =&gt;
        ...props, // Props coming from index.js, passed through the internal URL
        dataFromAnAPI: 'Hello there'

} }

The initial props must be serializable using

. Beware

Note: for convenience,

has the same signature than the Next.js one. However, it's a totally independent and standalone implementation (you don't need Next.js to use it).

Serving the Fragments

To serve the fragments, React ESI provides a ready to use controller compatible with Express:

// server.js
import express from 'express';
import { path, serveFragment } from 'react-esi/lib/server';

const server = express(); server.use((req, res, next) => { // Send the Surrogate-Control header to announce ESI support to proxies (optional with Varnish, depending of your config) res.set('Surrogate-Control', 'content="ESI/1.0"'); next(); });

server.get(path, (req, res) => // "path" default to /_fragment, change it using the REACT_ESI_PATH env var serveFragment( req, res, // "fragmentID" is the second parameter passed to the "WithESI" HOC, the root component used for this fragment must be returned fragmentID => require(./components/${fragmentID}).default) );

// ... // Other Express routes come here


Alternatively, here is a full example using a Next.js server:

// server.js
import express from 'express';
import next from 'next';
import { path, serveFragment } from 'react-esi/lib/server';

const port = parseInt(process.env.PORT, 10) || 3000 const dev = process.env.NODE_ENV !== 'production' const app = next({ dev }) const handle = app.getRequestHandler()

app.prepare().then(() => { const server = express(); server.use((req, res, next) => { // Send the Surrogate-Control header to announce ESI support to proxies (optional with Varnish) res.set('Surrogate-Control', 'content="ESI/1.0"'); next(); });

server.get(path, (req, res) => serveFragment(req, res, fragmentID => require(./components/${fragmentID}).default) ); server.get('*', handle); // Next.js routes

server.listen(port, err => { if (err) throw err; console.log(&gt; Ready on http://localhost:${port}); }); });


  • Support Varnish, Cloudflare Workers, Akamai, Fastly and any other cache systems having ESI support
  • Written in TypeScript
  • Next.js-friendly API

Environment Variables

React ESI can be configured using environment variables:

    : a secret key used to sign the fragment URL (default to a random string, it's highly recommended to set it to prevent problems when the server restart, or when using multiple servers)
    : the internal path used to generate the fragment, should not be exposed publicly (default:

Passing Attributes to the

To pass attributes to the

 element generated by React ESI, pass a prop having the following structure to the HOC:
  esi: {
    attrs: {
      alt: "Alternative text",
      onerror: "continue"


The Cache is Never Hit

By default, most cache proxies, including Varnish, never serve a response from the cache if the request contains a cookie. If you test using

or a similar local domain, clear all pre-existing cookies for this origin. If the cookies are expected (e.g.: Google Analytics or ad cookies), then you must configure properly your cache proxy to ignore them. Here are some examples for Varnish.

Design Considerations

To allow the client-side app to reuse the props fetched or computed server-side, React ESI injects

 tags containing them in the ESI fragments.
After the assembling of the page by the cache server, these script tags end up mixed with the legit HTML.
These tags are automatically removed from the DOM before the rendering phase.

Going Further

React ESI plays very well with advanced cache strategies including:

  • Cache invalidation (purge) with cache tags (Varnish / Cloudflare)
  • Warming the cache when data change in the persistence layer (Varnish)

Give them a try!

Vue.js / Nuxt

We love Vue and Nuxt as much as React and Next, so we're a currently porting React ESI for this platform. Contact us if you want to help!


Created by Kévin Dunglas. Sponsored by

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.