react-relay-network-modern-ssr

1.4.0 verified Sat Apr 25 auth: no javascript maintenance

Server-side rendering middleware for the react-relay-network-modern package, enabling data fetching and cache management for Relay Modern during SSR. Current stable version is 1.4.0 (released 2020-03-02), with infrequent releases. It provides a RelayServerSSR class that supports three modes: default fetch-based, direct schema injection with graphql-js, and asynchronous context preparation. Key differentiator: it requires two-pass rendering to populate the Relay store before final HTML output and ships TypeScript definitions. It is unmaintained since 2020 and relies on peer dependencies graphql, react-relay, and react-relay-network-modern.

Common errors

error Cannot find module 'relay-runtime' ↓

cause Missing peer dependency 'relay-runtime' (or 'react-relay' for older versions).

fix

Install react-relay: npm install react-relay

error TypeError: relayServerSSR.getMiddleware is not a function ↓

cause Incorrect import path – using main export instead of /lib/server.

fix

Use import RelayServerSSR from 'react-relay-network-modern-ssr/lib/server'

error Module not found: Can't resolve 'graphql' ↓

cause Missing peer dependency 'graphql' when using schema option.

fix

Install graphql: npm install graphql

Warnings

deprecated Removed .mjs support in v1.3.0 – ES modules are no longer provided. ↓

fix Use CommonJS require() or transpile with bundler (e.g., Webpack, Rollup).

gotcha Must call relayServerSSR.getCache() after initial render to collect all query payloads. ↓

fix Always call await relayServerSSR.getCache() before second render.

gotcha If using middleware without schema argument, ensure fetch is available (Node 18+) or polyfill. ↓

fix Provide a schema object to getMiddleware() or install a fetch polyfill like node-fetch.

breaking Changed peer dependency from 'relay-runtime' to 'react-relay' in v1.2.1 – projects using relay-runtime directly may break. ↓

fix Ensure react-relay (not relay-runtime) is listed in peerDependencies.

Install

npm install react-relay-network-modern-ssr

yarn add react-relay-network-modern-ssr

pnpm add react-relay-network-modern-ssr

Imports

RelayServerSSR
wrong
```
import { RelayServerSSR } from 'react-relay-network-modern-ssr'
```
correct
```
import RelayServerSSR from 'react-relay-network-modern-ssr/lib/server'
```
Default export from lib/server — named import does not work. Also available via require: const RelayServerSSR = require('react-relay-network-modern-ssr/lib/server').default

RelayClientSSR

wrong

import { RelayClientSSR } from 'react-relay-network-modern-ssr/lib/client'

correct

import RelayClientSSR from 'react-relay-network-modern-ssr/lib/client'

Default export from lib/client — named import does not work. For client-side hydration.

SSRCacheMiddleware

wrong

import { SSRCacheMiddleware } from 'react-relay-network-modern-ssr'

correct

import SSRCacheMiddleware from 'react-relay-network-modern-ssr/lib/client'

SSRCacheMiddleware is an alias for RelayClientSSR; use default import from lib/client.

Quickstart

Complete Express SSR setup with RelayServerSSR – two-pass rendering, schema injection, cache retrieval, and HTML serialization.

import express from 'express';
import ReactDOMServer from 'react-dom/server';
import { RelayNetworkLayer } from 'react-relay-network-modern';
import RelayServerSSR from 'react-relay-network-modern-ssr/lib/server';
import serialize from 'serialize-javascript';
import { Environment, Network, RecordSource, Store } from 'relay-runtime';
import schema from './schema';

const app = express();

app.get('/*', async (req, res, next) => {
  const relayServerSSR = new RelayServerSSR();

  const network = new RelayNetworkLayer([
    relayServerSSR.getMiddleware({
      schema,
      contextValue: {}
    })
  ]);

  const source = new RecordSource();
  const store = new Store(source);
  const relayEnvironment = new Environment({ network, store });

  // First render to kick off data fetching
  ReactDOMServer.renderToString(<App relayEnvironment={relayEnvironment} />);

  // Wait for all queries to complete
  const relayData = await relayServerSSR.getCache();

  // Second render with primed store
  const appHtml = ReactDOMServer.renderToString(
    <App
      relayEnvironment={new Environment({
        network: Network.create(() => relayData[0][1]),
        store
      })}
    />
  );

  res.status(200).send(`
    <html>
      <body>
        <div id="react-root">${appHtml}</div>
        <script>window.__RELAY_BOOTSTRAP_DATA__ = ${serialize(relayData)};</script>
        <script src="/assets/bundle.js"></script>
      </body>
    </html>
  `);
});

app.listen(3000);