Dynamic rendering with InstantSearch.js

InstantSearch.js doesn’t support server-side rendering, but you can get the same benefits by implementing dynamic rendering.

Dynamic rendering is now considered a workaround instead of a recommended approach and Rendertron, the tool mentioned in this guide, is deprecated. You can use server-side rendering with React InstantSearch and Vue InstantSearch.

InstantSearch.js doesn’t support server-side rendering (SSR). However, it’s possible to get some of the SSR benefits using another technique: dynamic rendering.

Dynamic rendering

Dynamic rendering lets you switch between client-side rendered and pre-rendered content for specific user agents, typically search engine user agents. This means that whenever your server receives a request, it first looks at the user agent to determine whether it’s coming from a search engine or a regular user.

• If the request is coming from a search engine, the response is proxied through a headless browser that pre-renders it.
• If the request is coming from a regular user, the response is rendered client-side.

Build an InstantSearch app

The easiest way to setup a basic InstantSearch app is using create-instantsearch-app. Install create-instantsearch-app and create your app.

Shell

npm install -g create-instantsearch-app@latest
create-instantsearch-app my-app

Feel free to pick any InstantSearch flavor your like. Pick the default values for the rest of the options.

Run the build command and confirm it produced a dist/ folder.

Shell

cd my-app
npm run build

Add a basic Express.js server that will serve static files.

Shell

npm install --save express
touch index.js

JavaScript

// index.js
const express = require('express');
const app = express();

app.use(express.static('dist'));

const port = process.env.PORT || 3000;
app.listen(port, err => {
  if (err) {
    console.error('failed to start server.');
    return;
  }
  console.log(`server started at http://localhost:${port}/`);
});

Now run the server and visit http://localhost:3000 to make sure everything is working.

Shell

node index.js

Set up and configure a dynamic renderer

Google recommends using either rendertron (free, self-hosted) or prerender.io (fully hosted). This example uses rendertron.

Shell

npm install -g rendertron
PORT=3001 rendertron &

The pre-renderer is now listening on port 3001 and ready to render JavaScript generated content into HTML.

Proxy your requests through Rendertron

You need to send every request with the Content-Type: text/html header and the relevant user agent to the URL of Rendertron: http://localhost:3001/render.

Depending on your stack, there are multiple ways you can achieve this kind of proxying, but if you’re using an Express.js server, rendertron-middleware can handle this proxying for you.

Shell

npm install --save rendertron-middleware

JavaScript

const rendertronMiddleware = require('rendertron-middleware');

/* ... */

app.use(
  rendertronMiddleware.makeMiddleware({
    proxyUrl: `http://localhost:3001/render/`, // rendertron address with a /render/ suffix
    timeout: 60 * 1000,
    userAgentPattern: /googlebot|bingbot/i // by default
  })
);

app.use(express.static('dist'));

/* ... */

Feel free to adjust the userAgentPattern or use the default values.

Close and restart your server, then run this curl command to confirm pre-rendering works.

Shell

curl --user-agent "googlebot" http://localhost:3000/