Gatsby Server Rendering APIs

The file gatsby-ssr.js lets you alter the content of static HTML files as they are being Server-Side Rendered (SSR) by Gatsby and Node.js. To use the Gatsby SSR APIs, create a file called gatsby-ssr.js in the root of your site. Export any of the APIs you wish to use in this file.

The APIs wrapPageElement and wrapRootElement exist in both the SSR and browser APIs. If you use one of them, consider if you should implement it in both gatsby-ssr.js and gatsby-browser.js so that pages generated through SSR with Node.js are the same after being hydrated with browser JavaScript.

Usage

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

APIs

onPreRenderHTML Function
Source
123

(apiCallbackContext: object, pluginOptions: pluginOptions) => undefined

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
    • pathname string

      The pathname of the page currently being rendered.

    • getHeadComponents ReactNode[]

      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 ReactNode[]

      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 ReactNode[]

      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

    Object containing options defined in gatsby-config.js

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 Function
Source
123

(apiCallbackContext: object, pluginOptions: pluginOptions) => undefined

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

    Object containing options defined in gatsby-config.js

Example

// Import React so that you can use JSX in HeadComponents
const React = require("react")

const HtmlAttributes = {
  lang: "en"
}

const HeadComponents = [
  <script key="my-script" src="https://gatsby.dev/my-script" />
]

const BodyAttributes = {
  "data-theme": "dark"
}

exports.onRenderBody = ({
  setHeadComponents,
  setHtmlAttributes,
  setBodyAttributes
}, pluginOptions) => {
  setHtmlAttributes(HtmlAttributes)
  setHeadComponents(HeadComponents)
  setBodyAttributes(BodyAttributes)
}

replaceRenderer Function
Source
12

(apiCallbackContext: object, pluginOptions: pluginOptions) => undefined

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
    • pathname string

      The pathname of the page currently being rendered.

    • bodyComponent ReactNode

      The React element to be rendered as the page body

    • 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

    Object containing options defined in gatsby-config.js

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 Function
Source
12

(apiCallbackContext: object, pluginOptions: pluginOptions) => ReactNode

Allow a plugin to wrap the page element.

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

Note: There is an equivalent hook in Gatsby’s Browser API. It is recommended to use both APIs together. For example usage, check out Using i18n.

Parameters

  • destructured object
    • element ReactNode

      The “Page” React Element built by Gatsby.

    • props object

      Props object used by page.

  • pluginOptions object

    Object containing options defined in gatsby-config.js

Return value

ReactNode

Wrapped element

Example

const React = require("react")
const Layout = require("./src/components/layout").default

exports.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 Function
Source
12

(apiCallbackContext: object, pluginOptions: pluginOptions) => ReactNode

Allow a plugin to wrap the root element.

This is useful to set up any Provider components that will wrap your application. For setting persistent UI elements around pages use wrapPageElement.

Note: There is an equivalent hook in Gatsby’s Browser API. It is recommended to use both APIs together. For example usage, check out Using redux.

Parameters

  • destructured object
    • element ReactNode

      The “Root” React Element built by Gatsby.

  • pluginOptions object

    Object containing options defined in gatsby-config.js

Return value

ReactNode

Wrapped element

Example

const React = require("react")
const { Provider } = require("react-redux")

const createStore = require("./src/state/createStore")
const store = createStore()

exports.wrapRootElement = ({ element }) => {
  return (
    <Provider store={store}>
      {element}
    </Provider>
  )
}
Edit this page on GitHub