Utilities for hydrating server-rendered React apps.
$ yarn add @shopify/react-hydrate
This library is intended to assist with "progressive hydration", a pattern where you fully render an application on the server, but wait to hydrate parts of it when it reaches the client. Typically, doing different work on the server and client would result in the server markup being thrown out by React’s initial reconciliation.
This library avoids that issue by rendering a wrapping
div around the content on the server, adding an ID to that element, and setting the
dangerouslySetInnerHTML prop on the client to the resulting server markup in order to avoid mismatches. Once you have done whatever work on the client to load the necessary components, this hardcoded markup is removed, allowing the React tree to take over.
There are two key pieces to making this work. First, your server must render a
HydrationContext.Provider element around your React tree. This element will provide a
HydrationManager to the tree, which manages the identifiers that map server markup to client markup.
Note that if you use
@shopify/react-effect, you must reset the manager after each rendering pass. If you don’t, the identifiers will continue to increment during each pass, and will not match between client and server. You must also use a new
HydrationManager for every request to prevent identifiers leaking between different renders.
Once the server is in place, you can start to use the
Hydrator component. This component will do different things depending on its children:
- If children are passed (the server-side case), render those children normally, but inside of a
divwith an identifier that can be matched on the client.
- If children are not passed (the client-side case, because this is only used in cases where you will not have the code available to you on the client to render the same markup that was present on the server), render a
dangerouslySetInnerHTMLset to be the HTML of the original, server-rendered markup.
Note: you probably don’t need to know the internals of how progressive hydration works, unless you’re really interested. This package will primarily be used by other tools that manage asynchronous component loading, such as
;;// This is a hypothetical component that knows how to load a component// asynchronously, but can also potentially access it synchronously on the// server. So, the server will immediately have access to the component and// can render it for the initial page load, but the client will have to wait// until it is loaded asynchronously. The Hydrator component stands in the middle// to bridge the gap and prevent the server markup from being thrown away.
You can optionally pass an
id prop to
Hydrator, which will be used to prefix the identifier used to match server and client markup.