Gatsby Server Rendering APIs

The file gatsby-ssr.jsx/gatsby-ssr.tsx 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.

You can author the file in JavaScript or TypeScript.

The APIs wrapPageElement and wrapRootElement exist in both the SSR and browser APIs. You generally should implement the same components in both gatsby-ssr.js and gatsby-browser.js so that pages generated through SSR with Node.js are the same after being hydrated in the browser.

Usage

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

APIs

`onPreRenderHTML` Function
Source
1 2

(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
1 2

(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

(apiCallbackContext: object, pluginOptions: pluginOptions) => void | Promise<void>

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

Return value

void | Promise<void>

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

(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

(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
- pathname string
  The pathname of the page currently being rendered.
- 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

Gatsby Server Rendering APIs

Usage

APIs

Parameters

destructured object

pathname string

getHeadComponents ReactNode[]

replaceHeadComponents function

getPreBodyComponents ReactNode[]

replacePreBodyComponents function

getPostBodyComponents ReactNode[]

replacePostBodyComponents function

pluginOptions object

Example

onRenderBody FunctionSource12

Parameters

destructured object

pathname string

setHeadComponents function

setHtmlAttributes function

setBodyAttributes function

setPreBodyComponents function

setPostBodyComponents function

setBodyProps function

pluginOptions object

Example

Parameters

destructured object

pathname string

bodyComponent ReactNode

replaceBodyHTMLString function

setHeadComponents function

setHtmlAttributes function

setBodyAttributes function

setPreBodyComponents function

setPostBodyComponents function

setBodyProps function

pluginOptions object

Return value

void | Promise<void>

Example

wrapPageElement FunctionSource

Parameters

destructured object

element ReactNode

props object

pluginOptions object

Return value

ReactNode

Example

wrapRootElement FunctionSource

Parameters

destructured object

pathname string

element ReactNode

pluginOptions object

Return value

ReactNode

Example

`pathname` string

`getHeadComponents` ReactNode[]

`replaceHeadComponents` function

`getPreBodyComponents` ReactNode[]

`replacePreBodyComponents` function

`getPostBodyComponents` ReactNode[]

`replacePostBodyComponents` function

`pluginOptions` object

`onRenderBody` Function
Source
1 2

`pathname` string

`setHeadComponents` function

`setHtmlAttributes` function

`setBodyAttributes` function

`setPreBodyComponents` function

`setPostBodyComponents` function

`setBodyProps` function

`pluginOptions` object

`pathname` string

`bodyComponent` ReactNode

`replaceBodyHTMLString` function

`setHeadComponents` function

`setHtmlAttributes` function

`setBodyAttributes` function

`setPreBodyComponents` function

`setPostBodyComponents` function

`setBodyProps` function

`pluginOptions` object

`wrapPageElement` Function
Source

`element` ReactNode

`props` object

`pluginOptions` object

`wrapRootElement` Function
Source

`pathname` string

`element` ReactNode

`pluginOptions` object