Gatsby Server Rendering APIs

APIs



Reference

onRenderBody

Called after every page Gatsby server renders while building HTML so you can set head and body components to be rendered in your html.js.

Gatsby does a two-pass render for HTML. It loops through your pages first rendering only the body and then takes the result body HTML string and passes it as the body prop to your html.js to complete the render.

It’s often handy to be able to send custom components to your html.js. For example, it’s a very common pattern for React.js libraries that support server rendering to pull out data generated during the render to add to your HTML.

Using this API over replaceRenderer is preferable as multiple plugins can implement this API where only one plugin can take over server rendering. However, if your plugin requires taking over server rendering then that’s the one to use

Parameters

destructured object
pathname {string}

The pathname of the page currently being rendered.

setHeadComponents {function}

Takes an array of components as its first argument which are added to the headComponents array which is passed to the html.js component.

setPreBodyComponents {function}

Takes an array of components as its first argument which are added to the preBodyComponents array which is passed to the html.js component.

setPostBodyComponents {function}

Takes an array of components as its first argument which are added to the postBodyComponents array which is passed to the html.js component.

setBodyProps {function}

Takes an object of data which is merged with other body props and passed to html.js as bodyProps.

pluginOptions {Object}

Example

import helmet from "react-helmet"

exports.onRenderBody = ({ setHeadComponents }, pluginOptions) => {
  setHeadComponents([
    helmet.title.toComponent(),
    helmet.meta.toComponent(),
    helmet.link.toComponent(),
  ])
}

replaceRenderer

Replace the default server renderer. This is useful for integration with Redux, css-in-js libraries, etc. that need custom setups for server rendering.

Parameters

destructured object
replaceBodyHTMLString {function}

Call this with the HTML string you render. WARNING if multiple plugins implement this API it’s the last plugin that “wins”. TODO implement an automated warning against this.

setHeadComponents {function}

Takes an array of components as its first argument which are added to the headComponents array which is passed to the html.js component.

setPreBodyComponents {function}

Takes an array of components as its first argument which are added to the preBodyComponents array which is passed to the html.js component.

setPostBodyComponents {function}

Takes an array of components as its first argument which are added to the postBodyComponents array which is passed to the html.js component.

setBodyProps {function}

Takes an object of data which is merged with other body props and passed to html.js as bodyProps.

pluginOptions {Object}

Example

// From gatsby-plugin-glamor
import { renderToString } from "react-dom/server"
import inline from "glamor-inline"

exports.replaceRenderer = ({ bodyComponent, replaceBodyHTMLString }) => {
  const bodyHTML = renderToString(bodyComponent)
  const inlinedHTML = inline(bodyHTML)

  replaceBodyHTMLString(inlinedHTML)
}