react-waterfall-render

react-waterfall-render

Renders nested React components with asynchronous cached loading.

Useful for GraphQL clients (e.g. graphql-react) and server side rendering.

Setup

To install with npm, run:

npm install react-waterfall-render

Use the WaterfallRenderContext in React components to declare asynchronous cached loading, and use the function waterfallRender to server side render your React app in a fully loaded state.

Support

• Node.js: ^10.17.0 || ^12.0.0 || >= 13.7.0
• Browsers: > 0.5%, not OperaMini all, not dead

API

Table of contents

• function waterfallRender
• member WaterfallRenderContext
• type DeclareLoading
• type ReactNode

function waterfallRender

Resolves a React node rendered with all data loaded within cached.

It repeatedly renders the React node and awaits any loading cache promises declared within (using the declare loading function via WaterfallRenderContext), until no further loading is declared; implying all data has loaded and is rendered from cache.

If server side rendering, afterwards the cache should be serialized for hydration on the client prior to the initial client side render.

Intended for use in a Node.js environment for server side rendering, but could potentially be used for preloading components in modern browser environments that support async functions, etc.

Parameter	Type	Description
reactNode	ReactNode	React virtual DOM node.
render	Function	Synchronous React render function, e.g. ReactDOMServer.renderToStaticMarkup (faster), or ReactDOMServer.renderToString (slower).

Returns: Promise<*> — Resolves the final render result, typically a HTML string.

Examples

Ways to import.

import { waterfallRender } from 'react-waterfall-render';

import waterfallRender from 'react-waterfall-render/public/waterfallRender.js';

Ways to require.

const { waterfallRender } = require('react-waterfall-render');

const waterfallRender = require('react-waterfall-render/public/waterfallRender');

How to server side render a React app in Node.js.

const { renderToStaticMarkup } = require('react-dom/server');
const { waterfallRender } = require('react-waterfall-render');
const App = require('./components/App');

waterfallRender(<App />, renderToStaticMarkup).then((html) => {
  // Do something with the HTML string…
});

---

member WaterfallRenderContext

React context object for making the declare loading function available within components when rendering with waterfallRender.

Type: object

Property	Type	Description
Provider	Function	React context provider component.
Consumer	Function	React context consumer component.

Examples

Ways to import.

import { WaterfallRenderContext } from 'react-waterfall-render';

import WaterfallRenderContext from 'react-waterfall-render/public/WaterfallRenderContext.js';

Ways to require.

const { WaterfallRenderContext } = require('react-waterfall-render');

const WaterfallRenderContext = require('react-waterfall-render/public/WaterfallRenderContext');

Use within a component with the useContext React hook.

const { useContext } = require('react');
const { WaterfallRenderContext } = require('react-waterfall-render');

const declareLoading = useContext(WaterfallRenderContext);

---

type DeclareLoading

Declares loading cache promises to waterfallRender. Available within React components via WaterfallRenderContext.

Type: Function

Parameter	Type	Description
promises	…Promise<*>	Promises that resolve once loading data has been cached. The values resolved don’t matter. Multiple arguments can be used, similar to how Array.push works.

Examples

Loading data in a React component within a server and client side rendered app.

const { useContext } = require('react');
const { WaterfallRenderContext } = require('react-waterfall-render');
const useUserProfileData = require('../hooks/useUserProfileData');
const UserProfile = require('./UserProfile');

module.exports = function UserPage({ userId }) {
  const declareLoading = useContext(WaterfallRenderContext);
  const { load, loading, cache } = useUserProfileData(userId);

  // For this example, let’s assuming loading errors are cached.
  if (cache) return <UserProfile data={cache} />;

  if (!loading) {
    const userDataPromise = load();

    // Only present when the app is server side rendered using the function
    // `waterfallRender`.
    if (declareLoading) {
      declareLoading(userDataPromise);

      // This render is on the server and will be discarded anyway for a
      // re-render once the declared loading promises resolve, so it’s
      // slightly more efficient to render nothing; particularly if the
      // loading state is expensive to render.
      return null;
    }
  }

  return 'Loading…';
};

---

type ReactNode

A React virtual DOM node; anything that can be rendered.

Type: undefined | null | boolean | number | string | React.Element | Array<ReactNode>