Server-Side Rendering (SSR) allows you to render a page at run-time with data that is fetched when a user visits the page.The server generates the full HTML during HTTP request and sends it to the user. The API is focused on data fetching outside of the Gatsby data layer.

Note: This feature requires running NodeJS server.It is currently fully supported withgatsby serve and inGatsby Cloud.

Creating server-rendered pages

You can create server-rendered pagesthe same way as regular pages (including using the File System Route API).

The main difference is that page component must export an async function calledgetServerData:

When a page component exportsgetServerData function, Gatsby treats all pages built with this componentas server-rendered.

Thecontext parameter is an object with the following keys:

• headers: The request headers
• method: The request method, e.g.GET
• url: The request URL
• query: An object representing the query string
• params: If you useFile System Route API the URL path gets passed in asparams. For example, if your page is atsrc/pages/{Product.name}.js theparams will be an object like{ name: 'value' }.

getServerData can return an object with several possible keys:

• status (optional): The HTTP status code that should be returned. Should be avalid HTTP status code.
• props (optional): Object containing the data passed toserverData page prop. Should be a serializable object.
• headers (optional): Object containingheaders that are sent to the browser and caching proxies/CDNs (e.g., cache headers).

UseserverData prop in React page component

Theprops object you return fromgetServerData gets passed to the page component asserverData prop.

Interplay with build-time GraphQL queries

Server-rendered pages also support regular Gatsby GraphQL page queries. The page query is executed at build time,and the data is passed to React component as adata prop on each render (along with theserverData prop).

Keep in mind thatdata will be the same every time the page renders, butserverData will change according to return value of yourgetServerData function.Runtime GraphQL queries are not supported yet.

Working with server-rendered pages locally

Server-rendered pages work with bothgatsby develop andgatsby serve. The page will bere-generated on each request.

Using in production

Server-Side Rendering requires a running NodeJS server. You can put NodeJS runninggatsby servebehind a content delivery network (CDN) likeFastly, however that also requires additional infrastructure (like monitoring, logging, and crash-recovery).

Complete setup with auto-scaling is available for you inGatsby Cloud out-of-the-box.

How it works

For SSR every request only runs on server-side. On Gatsby Cloud the request is sent to a worker process that runs yourgetServerData function, passes this data to React component and returns HTML back to the user. By default, every request is a cache miss and for caching you’ll need to set custom HTTP Cache-Control headers.

When you directly visit a page you’ll get served the HTML. If you request a page on client-side navigation through Gatsby’s Link component the response will be JSON. Gatsby’s router uses this to render the page on the client.

This all happens automatically and you’ll only need to define agetServerData function in your page. You can’t export it from non-page files.

Additional Resources

• How-To Guide: Server-Side Rendering
• Conceptual Guide: Rendering Options