Relay modern: SSR and next.js

Photo by Michał Parzuchowski on Unsplash

Update [May 2021]: I’ve updated the example to work with the new versions of Next.js, React and Relay. This was done because the example did not work with latest version of Relay. I’ve updated the URLs to reflect the new commits and highlighted the changes in the article wherever appropriate. Old commits still exist in the remote repository.

Next.js is a powerful and versatile framework. It is pretty simple to use and the documentation is pretty great. But some tasks are tricky to handle on the server side. One of them is making Relay work.

TL;DR

Try the official next.js example first. If that works for you, I suggest you go with it. However, the official example needs you to write your graphql queries and fragments a certain way. If you don’t like that, you can write your code as you normally would and then use custom document and Relay network modern SSR to make it work.

How to read this article

The article starts with a discussion of SSR. I strongly advise you to read that once. You can selectively read the article after that.

Working with the example

I have used a very basic next.js app. You can either clone it and work on it as we go. Or you can directly read the code from github. I have added links to the files wherever needed. The code is small, clean and understandable.

This Article is divided into three cases / approaches to SSR. The first one is basic — no SSR support. I suggest you go through it to understand the example.

The next.js approach

If you feel that the next.js approach works for you, I suggest you move on to that. You don’t have to read anything else.

The universal approach

If you feel that the universal approach works for you, I suggest you to skip the next.js approach and move directly to that. You don’t have to read anything else.

Table of contents

1. Introduction
2. A basic Relay app
3. A barebones example.
4. Data availability — the next.js way
5. Data availability — the universal way

Introduction

This article will explore the problems encountered while using Relay on the server side. We shall see different approaches to migitate those problems and compare them. We will explore these solutions with a very simple example. We move in steps and each step is represented as a commit in the example.

Server side rendering

With SSR set up, your initial app rendering is a little different that the normal React lifecycle. We assume that we are using function components. The normal React flow is following:

1. Render the Virtual DOM and commit it to HTML DOM.
2. After the commit phase, let components know that the tree is mounted.
3. Components run any side effects (dictated by useEffect hooks).

With SSR, the flow is as follows:

1. Render the Virtual DOM on a node.js server. We must make sure that the rendering code does not use any browser based Web APIs like document or window object. That is to ensure that app renders on server without any issues. Any Web APIs should be used in side effects.
2. Take the output of rendering and make it into an HTML page.
3. Serve the HTML page to the client.
4. React again renders the Virtual DOM on the client side.
5. React thenb compares it with HTML recieved and then links the generated Virtual DOM to the HTML DOM. This is called hydration.
6. After hydration, React lets components know that the app is ready.
7. Components run any side effects (dictated by useEffect hooks).

Note: If the Virtual DOM rendered on client side does not match the recieved HTML, client side Virtual DOM overrides the HTML recieved from the server. In such a case, React provides a hydration warning in development mode.

Issues with Relay

The normal React flow with Relay is as follows:

1. Virtual DOM is rendered. That fires up the graphql queries.
2. Until the data is not available, you render a placeholder like a loading indicator.
3. When the data comes in, Relay re-renders the app with the graphql data.

There are two hinderances to using Relay at the server side:

1. Data fetching should work on server side. For example if you use fetch to get your data, that won’t work on the server.
2. Data should be available before the app is rendered on server. If that is not the case, recieved HTML will have the loading indicator instead of the graphql data.

Checking the HTML recieved from server

Before loading the page, disable the Javascript in your browser. After that, you’ll be able to see the HTML recieved from the server as it is. That is because React does not run on the client side anymore.

To disable Javascript in chrome, open the DevTools. Then press ctrl + shift + P. Search for Disable Javascript option.

A basic Relay app

We shall use the github graphql API. Our example will get your username and render it on the screen. To get started, create a personal access token so that you can use the API. After that, you can clone this example. We make this example SSR ready in steps. Each step is reflected as a commit. You can clone the example by:

git clone https://github.com/yashmahalwal/relay-ssr.git

Before starting, make an environment file in the project root and save it as .env.local. Enter your personal access token inside it.

NEXT_PUBLIC_GITHUB_TOKEN=Your github personal token

Finally, run npm install to get all the dependencies.

1. A barebones example

Now, switch to the corresponding commit . To do that, run

g̶i̶t̶ ̶c̶h̶e̶c̶k̶o̶u̶t̶ ̶7̶2̶7̶7̶9̶2̶5̶6̶a̶e̶2̶3̶8̶5̶5̶3̶e̶1̶2̶d̶b̶f̶9̶6̶d̶8̶5̶7̶2̶2̶f̶6̶7̶6̶a̶9̶a̶e̶6̶f̶
# Update May 2021
git checkout 39ea3600b413b006083def72055e37a7ec0e96d3

I want you to take a minute to look around. First off, check the relay environment file. It is almost same as the relay docs example with two differences:

1. The URL is set to github’s API. It also passes a header for github authentication.
2. It exports a function that returns a new environment object instead of simply exporting an environment object.

The second part is necessary. On the server side, a single copy of the environment.ts module is used for all the clients. So if we export an environment object, it will be shared by all the clients. That means that they will share a common store. This in turn means that a user can see the data of another user. That is a memory leak. To overcome that, we create a new environment on every render.

I use relay-hooks to make things easier. Relay ships with its own set of hooks but they leverage React’s experimental concurrent mode which does not work well with SSR at this point.

It needs you to provide an environment on the top level as context. That environment is used everywhere. If you look at the custom app, you will see that happening.

FInally, come to the index page. I fire a query to get the username of the authenticated user.

query pagesQuery {
  viewer {
    login
  }
}

Let us see it happening in action. Make sure that you ran npm install in the project root. After that, run npm run dev to start the development server.

Now I want you to go to your browser and open the URL for the development server. By default, it will be set to http://localhost:3000/.

The username query

Let us take a look at the markup recieved from the server. Disable Javascript in your browser and try again.

Server rendered markup

Ideally, we would expect the server side markup to contain the username. But since the server did not have our graphql data before rendering and it did not wait for the Relay’s queries to complete, we are stuck with the loading indicator.

Observations

1. Data fetching: If you look at the environment file, we use fetch at the network layer. It should throw error on the server side but it does not. That is because react-relay package indirectly depends on node-fetch. This package allows you to use fetch on node.js as you would in the browser. You can verify the dependency by running npm ls in the project root.

output of npm ls command

2. Server side markup: Server sent us a loading indicator instead of the final result. If we need the final result, we must make sure that the data is available before our page is rendered.

Next steps

There were two issues with Relay on server side — data fetching and data availability. Relay takes care of data fetching. You need to take care of data availability. Thankfully, we have a trick up our sleeve that will help with this. Everything we do will be based on the following property of Relay store:

The store constructor from relay-runtime accepts a records argument. If we provide an object here, the new store is populated with the entries from this object.

We take the following steps to make data available before rendering:

1. Collect your graphql queries and run them to get their results.
2. Process these results as store records.
3. Pass these records to your app while rendering. App should create the environment using these records.
4. Set your fetch policy to use the store during rendering. That means if Relay finds data in the store, that will be used for rendering. It will no longer wait for the network request and therefore won’t render the loading indicator.

Ideally, you should set fetch policy to store-or-network. In that case, Relay will use data in the store to render. If the required data is not present, Relay will send out a network request. In case you want to do initial rendering using store but update it later, use store-and-network. Here, Relay renders the app using its store. While it does that, it also sends a network request. When the network request comes in, Relay re-renders with the new data.

2. Data availability — the next.js way

Next.js has first class support for injecting external data into your application before it renders. But that requires you to write your components a certain way. You need to break your code into pages and each page should specify its data requirements in getStaticProps or getServerSideProps. If you are writing a new application, I suggest you go with it. This way is very efficient and also blends well with the next.js workflow.

An example of making Relay work that way is provided in the next.js repo. But for the sake of completeness, I will cover it here. Here is the basic idea:

1. For each page that needs graphql data, write a query specifying its needs.
2. In data fetching handler of the page, execute the query using fetchQuery.
3. Take the records from the result of query and pass it to the page as props.
4. Inside the page, use these records to create an environment. Use this environment for rendering.
5. These records are always available with the page before rendering — on server side and on the client side.

Let us switch our example to this stage. To do so, get to the corresponding commit.

g̶i̶t̶ ̶c̶h̶e̶c̶k̶o̶u̶t̶ ̶4̶2̶d̶c̶8̶e̶6̶9̶0̶b̶1̶6̶3̶c̶1̶c̶8̶c̶2̶4̶d̶8̶a̶6̶5̶4̶f̶e̶1̶0̶5̶a̶6̶6̶3̶d̶6̶7̶0̶e̶
# Update May 2021
git checkout 24a791bb1b0fccc5d34593f0d1039f27013ca549

Now let us explore the changes. First off, take a look at the relay environment. The function now accepts an argument for records. The second thing that I have done is moved the RelayEnvironmentProvider from _app.tsx to my page. You can see that by checking the app page and the index page.

The most interesting part is the index page. I have done 3 changes here:

1. Added a getStaticProps to run the graphql query.
2. Refactored the page into a wrapper and its content.
3. Added RelayEnvironmentProvider to the wrapper.

Now take a look at getStaticProps function. It creates a new store and runs the query. After the query is complete, it extracts all records from the store and passes them to the page as props. Page extracts these records from props and creates an environment using them. Note how much refactoring has gone into the page. If there are multiple pages, you have to do this for every page.

Let us see this in action. Before everything, check the server side markup. Disable Javascript and check out the development URL.

Server side rendered markup

This works as we wanted it to. Using this approach has two benefits:

1. Data is available before the app renders. So you do not need any extra re-renders.
2. The data is always available to the page before rendering. This means that even when the app hydrates on client side, there is no loading indicator.

No loading on hydration

The only downside here is that you have to write your components such that all the queries are available at the page level. If you are writing a new app, this is alright. But refactoring an old app can be a nightmare. And sometimes, you may not have control over all the components. For example, if some of the components are published as npm packages, you might not know anything about queries written inside them.

Next Steps

We attained data availability. But to do so, we sacrifice flexibility in structure. What if we wanted to retain the original application structure? What if we don’t want to refactor all our queries and keep everything as it was? The issue to that would be collecting all the queries. We don’t know where every query is. Some queries might be inside npm packages and would not be accessible to us directly. Thankfully, relay-tools collection has a solution just for this.

Relay network modern is a network layer for Relay environment. It comes with some very powerful middlewares that help you manage your network layer. Relay network modern SSR adds server side data collection support. Consider the barebones example. Our basic idea is this:

1. Render your app on the server and dispose the output.
2. Take the Relay environment used to render that app.
3. If Relay network modern SSR was used, you can access all the queries that were fired during rendering via Relay environment.
4. Wait for the queries to finish loading. Process the results as store records.
5. Render your app again and pass these records to your app while rendering. App should now create the environment using these records.

As before, you need to set your fetch policy to use the store during rendering. During the first render, Relay will display a loading indicator as the store is empty. But during the second render, it will render the required data from the store.

3. Data availability — the universal way

Get to the commit. This is built on the barebones example.

̶g̶i̶t̶ ̶c̶h̶e̶c̶k̶o̶u̶t̶ ̶7̶f̶f̶3̶5̶0̶f̶8̶5̶a̶5̶c̶d̶0̶7̶c̶8̶f̶a̶2̶b̶e̶9̶e̶4̶9̶7̶c̶9̶e̶8̶0̶a̶6̶0̶4̶4̶0̶c̶5̶
# Update May 2021
git checkout 2859e177b10add4dfdce7e836113b72c4e793a1f

Now, I want you to look at the environment.ts file again. This is same as the previous environment, only rewritten using the relay-network-modern and package relay-network-modern-ssr packages. Let us go ahead and install it.

npm i react-relay-network-modern react-relay-network-modern-ssr

Custom document

This is where the magic happens. Next.js has a HTML template. It renders your app on the server side and inserts the content inside the body tags of the HTML template. Then this HTML page is served to the client. On client side, the app hydrates and everything works as usual.

Next.js provides custom document component which used to customize the HTML template. This is very useful if you need to add some tags (usually meta tags to help SEO) in your HTML page that is served to the client. It is rendered only on the server side. Your app is rendered and inserted into the custom document as its child. The final HTML output is served to the client. If you have a static website, custom HTML template is calculated during build time. If you have a SSR web app, it is calculated on every request for the HTML page. But in any case, custom document is only rendered on the server.

The key here is that your app is rendered inside the custom document’s getInitialProps method during SSR — while creating the HTML page for the client. Remember that it does not render here on the client side. On client side, the app component is rendered independently and hydrated by comparing with the body tag of the HTML recieved from the server. Now that we know where the app is rendered on the server, we can start working.

Initial Environment

We will be rendering the app on server twice. First time, it will only be to collect all the queries for Relay. For this render, we will use a different environment. Take a moment to look at it. It is same as the normal environment but there are two differences:

1. Store is empty initially — not created with any records
2. We have added the relayServerSSR middleware to the network layer. This middleware will collect all the fired queries for us.

First render

Purpose of this render is to simply collect all the fired queries. Let us go to our custom document. If you look at it, you will see that we have added the getInitialProps method to the document. This will run before document is rendered. Look carefully at the method

1. Create the SSR customised environment with a relayServerSSR instance.
2. Take the currently requested page component. Modify the page rendering by wrapping the page in RelayEnvironmentProvider. That is done via enhanceComponent of the ctx.renderPage method.
3. Fire up the page rendering via Document.getInitialProps(ctx) and wait for it to finish.
4. Wait for all the queries to complete. That is done via await relayServerSSR.getCache().
5. Records for all the queries fired are processed from the environment via env.getStore().getSource().toJSON()

Now we have all the records that we wanted. If you skip to the end of the getInitialProps method, you will see that we have passed these records to the document as props. The document the converts it to a base64 string and adds it to the DOM. You can see that happening in the document’s render method. That is done to make our Relay data available on the client side.

Second render

Now that we have the records, let us render our custom app. During the first render, we simply rendered the page with our SSR customised environment. Second render will generate the actual markup. Let us continue reading the getInitialProps method.

If we had rendered custom app during the first render, our page would have used the standard environment provided by the app and not our SSR customised environment as the former would be in a nearer context to the page.

As you can see in the getInitialProps method, we render the app and pass the records to it as props. That is it. Now our app has relay data present beforehand. There are no loading indicators.

Custom App

During the first render, we skipped the app and directly rendered the Page. App will be used during the second server side render and on the client side renders. Let us take a quick look at the custom app. There are a few changes in the app:

1. App now accepts an optional prop records. On the second server side render, custom app recieves these from the custom document. On client side, this prop is not present. But we have encoded the relay store data in HTML DOM as base64 string. So we can read that data and get records from it.
2. A useMemo hook is added. Here, we check if there are any records in the props. If they are not present, we check if we’re on the client side. If that is so, we look inside the DOM to find base64 encoded string that parses into records. If neither is present, we return an empty object.
3. We create the environment using these records.

That is it. You can now write your queries and fragments as you like. This will handle all use cases.

Observations

1. There are two renders on the server side and one render on the client side (during hydration).
2. Our custom document is rendered only once on the server. Before rendering the custom document, we render our page and app using getInitialProps method of the custom document. This method runs before custom document is rendered.
3. Our page is rendered thrice — directly during the first server side render and as a child of custom app during the second server side render and the client side render.
4. Our custom app is rendered twice — during the second server side render and during the client side render.
5. First render is only done for collecting queries. It servers no other purpose. Second render is for generating HTML markup with Relay data. Relay data is available with the app before the second server side render.

Server side generated markup : Page loaded with JS disabled

6. When document renders, we encode the Relay data in a base64 string and put in the HTML DOM. On client side, app extracts this data before rendering. Therefore, Relay data is available with the app before the page renders on the client side.

No loading indicator on hydration : Page loaded with JS enabled

7. This approach is more flexible but less efficient than the next.js way. This involves two renders on the server side while the next.js approach requires only one render. It also requires us to encode the relay store data in the HTML DOM and serve that to the client which incurs network bandwidth overhead.

Conclusion

This covers most of the Relay SSR discussion. While I use next.js to demonstrate, the approaches discussed here work almost everywhere. You can build up on this and work towards more advanced functionality such as passing cookies between client and the graphql server.

Did this article help you? Was it missing something? Can it use a bit of trimming? How could it be better? Let me know in the comments below ; )