@webkom/react-prepare v1.0.1

react-prepare

react-prepare is a package that allows you to easily await asynchronous data requirements defined in your React components before server-side rendering.

The typical use-case is when a deeply-nested component needs to have a resource fetched from a remote HTTP server, such as GraphQL or REST API. Since renderToString is synchronous, when you call it on your app, this component won't render correctly.

One solution is to have a central router at the root of your application that knows exactly what data needs to be fetched before rendering. But this solution doesn't fit the component-based architecture of a typical React app. You want to declare data dependencies at the component level.

This is exactly what react-prepare does: it allows you to declare asynchronous dependencies at the component level, and make them work fine with server-side rendering as well as client-side rendering.

Example with react-redux

Let's assume you have defined an async action creator fetchTodoItems(userName) which performs HTTP request to your server to retrieve the todo items for a given user and stores the result in your redux state.

Your TodoList component definition would look like this:

import { usePreparedEffect } from 'react-prepare';
import { useDispatch, useSelector } from 'react-redux';
import { compose } from 'redux';

import { fetchTodoItems } from './actions';

const TodoList = ({ userName }) => {
  const dispatch = useDispatch();
  const items = useSelector(({ todoItems }) => todoItems);

  usePreparedEffect(
    'fetchTodoItems',
    () => {
      dispatch(fetchTodoItems(userName));
    },
    [userName],
  );

  return (
    <ul>
      {items.map((item, key) => (
        <li key={key}>{item}</li>
      ))}
    </ul>
  );
};

export default TodoList;

And your server-side rendering code would look like this:

import { renderToString } from 'react-dom/server';
import { createStore, applyMiddleware } from 'redux';
import thunkMiddleware from 'redux-thunk';
import { Provider } from 'react-redux';
import prepare from 'react-prepare';

import reducer from './reducer';

async function serverSideRender(userName) {
  const store = createStore(reducer, applyMiddleware(thunkMiddleware));
  const app = (
    <Provider store={store}>
      <TodoList userName={userName} />
    </Provider>
  );
  await prepare(app);
  return {
    html: renderToString(app),
    state: store.getState(),
  };
}

Your client should re-use the data fetched during server-side rendering directly, eg. assuming your injected it in window.__APP_STATE__:

const store = createStore(reducer, JSON.parse(window.__APP_STATE__));
render(
  <Provider store={store}>
    <TodoList userName={userName} />
  </Provider>,
  document.getElementById('app'),
);

API

usePreparedEffect(identifier: string, sideEffect: async () => Promise<void>, deps, opts)

Works like useEffect except that effects will be run on the server instead of the client the first time, when server-side rendering in enabled.

identifier

A string that uniquely identifies the effect. It is used to keep track of what effects have been run on the server.

sideEffect

An async function that performs the side effect. It should return a promise that will be awaited before server-side rendering.

deps

An array of dependencies. If any of the dependencies change, the effect will be run again. Just like useEffect it uses shallow, strict equality (===).

Like a normal useEffect, the effect will rerun on every render if nothing is passed to deps.

opts

An optional configuration object that can contain the following properties:

• opts.runSync (default: false):
  • true: When running prepare, the sideEffect-promise will be awaited before traversing further down the tree. (because of limitations in the current implementation, effects in the same component will be run in parallel)
  • false: When running prepare the promise will be awaited in parallell with all other prepared effects after the tree has been traversed.
• opts.serverOnly (default false):
  • When true the effect will only ever be run on the server. Any provided deps-array will be ignored, and the effect will not be run if the application is not server-side rendered.

withPreparedEffect(identifier: string, sideEffect: async (props) => Promise<void>, depsFn: (props) => [], opts)(Component)

Higher order component wrapper for usePreparedEffect, provided for compatibility with class components. Wraps Component with a component that contains a usePreparedEffect hook that calls sideEffect with the component's props.

identifier

A string that uniquely identifies the effect. It is used to keep track of what effects have been run on the server.

sideEffect

An async function that performs the side effect. It should return a promise that will be awaited before server-side rendering.

depsFn

A function that takes the component's props and returns an array of dependencies. If any of the dependencies change, the effect will be run again. Just like useEffect it uses shallow, strict equality (===).

If no depsFn is provided, an empty dependency-array will be used, and the sideEffect will never re-run (as opposed to usePreparedEffect, which would run sideEffect on every render).

opts

Available opts are the same as in usePreparedEffect.

async prepare(Element, ?opts) => string

Recursively traverses the element rendering tree, collecting all promises from usePreparedEffect and withPreparedEffect and awaits them as defined (either after traversing the tree, or before traversing further with runSync=true). It should be used (and await-ed) before calling renderToString on the server. If any of the side effects throws, prepare will also throw.

The return value is a string containing js-code to set a key on the window object, that will be used in the client-side rendering to avoid re-running any side effects.

Available opts is an optional configuration object:

• opts.errorHandler (default: e => {throw e}): Custom error handler used by each sideEffect. If a sideEffect throws, this is used as an error handler. If the error handler then throws, the prepare.

Notes

react-prepare tries hard to avoid object keys conflicts, but it does require setting a variable on the window object to store what side-effects are prepared. The single polluted key on the window object is @__REACT_PREPARE__@, which shouldn't be an issue.