Skip to main content

Gatsby Server Rendering APIs

Usage

Implement any of these APIs by exporting them from a file named gatsby-ssr.js in the root of your project.


APIs



Reference

onPreRenderHTML

Called after every page Gatsby server renders while building HTML so you can replace head components to be rendered in your html.js. This is useful if you need to reorder scripts or styles added by other plugins.

Parameters

destructured object
getHeadComponents {Array}

Returns the current headComponents array.

replaceHeadComponents {function}

Takes an array of components as its first argument which replace the headComponents array which is passed to the html.js component. WARNING if multiple plugins implement this API it’s the last plugin that “wins”.

getPreBodyComponents {Array}

Returns the current preBodyComponents array.

replacePreBodyComponents {function}

Takes an array of components as its first argument which replace the preBodyComponents array which is passed to the html.js component. WARNING if multiple plugins implement this API it’s the last plugin that “wins”.

getPostBodyComponents {Array}

Returns the current postBodyComponents array.

replacePostBodyComponents {function}

Takes an array of components as its first argument which replace the postBodyComponents array which is passed to the html.js component. WARNING if multiple plugins implement this API it’s the last plugin that “wins”.

pluginOptions {Object}

Example

// Move Typography.js styles to the top of the head section so they're loaded first.
exports.onPreRenderHTML = ({ getHeadComponents, replaceHeadComponents }) => {
  const headComponents = getHeadComponents()
  headComponents.sort((x, y) => {
    if (x.key === 'TypographyStyle') {
      return -1
    } else if (y.key === 'TypographyStyle') {
      return 1
    }
    return 0
  })
  replaceHeadComponents(headComponents)
}

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.

setHtmlAttributes {function}

Takes an object of props which will spread into the <html> component.

setBodyAttributes {function}

Takes an object of props which will spread into the <body> 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

const Helmet = require("react-helmet")

exports.onRenderBody = (
  { setHeadComponents, setHtmlAttributes, setBodyAttributes },
  pluginOptions
) => {
  const helmet = Helmet.renderStatic()
  setHtmlAttributes(helmet.htmlAttributes.toComponent())
  setBodyAttributes(helmet.bodyAttributes.toComponent())
  setHeadComponents([
    helmet.title.toComponent(),
    helmet.link.toComponent(),
    helmet.meta.toComponent(),
    helmet.noscript.toComponent(),
    helmet.script.toComponent(),
    helmet.style.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.

setHtmlAttributes {function}

Takes an object of props which will spread into the <html> component.

setBodyAttributes {function}

Takes an object of props which will spread into the <body> 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
const { renderToString } = require("react-dom/server")
const inline = require("glamor-inline")

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

  replaceBodyHTMLString(inlinedHTML)
}

wrapPageElement

Allow a plugin to wrap the page element.

This is useful for setting wrapper component around pages that won’t get unmounted on page change. For setting Provider components use wrapRootElement.

Note: There is equivalent hook in Browser API

Parameters

destructured object
element {object}

The “Page” React Element built by Gatsby.

props {object}

Props object used by page.

pathname {string}

Path of page.

Example

import React from "react"
import Layout from "./src/components/Layout"

export const wrapPageElement = ({ element, props }) => {
  // props provide same data to Layout as Page element will get
  // including location, data, etc - you don't need to pass it
  return <Layout {...props}>{element}</Layout>
}

wrapRootElement

Allow a plugin to wrap the root element.

This is useful to setup any Providers component that will wrap your application. For setting persistent UI elements around pages use wrapPageElement.

Note: There is equivalent hook in Browser API

Parameters

destructured object
element {object}

The “Root” React Element built by Gatsby.

Example

import React from "react"
import { Provider } from "react-redux"

import createStore from "./src/state/createStore"
const store = createStore()

export const wrapRootElement = ({ element }) => {
  return (
    <Provider store={store}>
      {element}
    </Provider>
  )
}