Debugging Server-Side Rendering Issues

Gatsby performs server-side rendering as part of its build process to facilitate faster page loads on the browser. Hooking into this rendering process involves creating or modifying the gatsby-ssr.js file. One of the server-side rendering APIs commonly leveraged during the build process is the replaceRenderer API, which can be used to customize or otherwise adjust the ways in which Gatsby renders out the contents of your site in static form. The most common use cases for this API generally involve the use of Redux, Styled Components, or other CSS-in-JS libraries that need to influence the markup rendered on the server side.

The replaceRenderer API is employed by various Gatsby plugins in the ecosystem to extend Gatsby so it supports these libraries, or any custom code that needs to modify how Gatsby generates its initial HTML output for the browser. This logic is executed solely during the build process (i.e., when gatsby build is executed), not during local development (gatsby develop). Sometimes, when multiple plugins require usage of the replaceRenderer API through their respective gatsby-ssr.js files, conflicts can occur between them.

If multiple plugins are simultaneously using the API at the same time, during the build process you’ll encounter an error that looks like the following, where default-site-plugin represents the local Gatsby site’s gatsby-ssr.js file, not the plugin’s:

warning replaceRenderer API found in these plugins:
warning gatsby-plugin-one, default-site-plugin
replace-renderer-api/
warning Duplicate replaceRenderer found, skipping gatsby-ssr.js for plugin: 
gatsby-plugin-one

The easiest way to correct an issue with conflicting gatsby-ssr.js files is to identify the offending replaceRenderer API code in the plugin’s gatsby-ssr.js file and copy it into your Gatsby site’s own gatsby-ssr.js file. This needs to happen because only the gatsby-ssr.js file for the site being built will be executed during the build process, which accepts only a single gatsby-ssr.js file.

NOTE

For a common real-world example of how to copy the replaceRenderer API code in a plugin’s gatsby-ssr.js file into the Gatsby site’s native gatsby-ssr.js file, consult the example involving Redux and Styled Components in the Gatsby documentation.