Working with React Server Components

This guide provides information about working with React Server Components in your Hydrogen app.

Fetching data on the server

All data fetching happens on the server and is never exposed to the client, unless you explicitly fetch data in a client component.

Hydrogen provides the following ways to fetch data from server components:

  • useShopQuery: A hook that allows you to make server-only GraphQL queries to the Storefront API.
  • useQuery: A simple wrapper around fetch that supports Suspense. You can use this function to call any third-party APIs.

Accessing Hydrogen components from client components

Because of the way tree-shaking works in Vite, avoid importing server components when referencing Hydrogen client components in one of your client components.

Hydrogen provides a special @shopify/hydrogen/client module to reference components that are safe to use within client components. You should use this import path when writing your client components.

Sharing state between client and server

Hydrogen provides a useServerState() hook with a setServerState() helper function, which allows components to paginate within collections, programmatically switch routes, or do anything that requires new data from the server.

Sharing state information between the client and server is important for common tasks, like page routing. The following diagram shows how the page state is shared between the client and server:

A diagram that illustrates the workflow for sharing state information between client and server

  1. App.server.jsx relies on the page state to choose the correct route to render. To change routes, the client updates the page state:

  2. The page state is sent to the server. This happens through a useServerResponse fetch call. It's a special server endpoint called /react which accepts state as a query parameter.

  3. The /react endpoint returns the wire representation for the new state.

  4. The state is partially hydrated (made interactive) and rendered into the DOM, similar to how the initial page was made interactive.

Hydrogen uses /react for routing, but also for any other state that needs to be synced to the server.

Using Context in React Server Components

React developers commonly use Context to share state among many different components in a render tree, without having to drill props down to each individual component.

Server context support is on the React team's roadmap, but it is not yet implemented. In order to share context between server components and client components, Hydrogen provides a workaround mechanism.

Provider components

Any client component with a name that ends in Provider receives special treatment during server-rendering and client hydration. This allows server components to share context during the server-side rendering and makes sure that the context is initialized as a client component on the client.


The following rules apply to Provider components:

  • You can't fetch server-only data from within Provider components. Instead, fetch data within server components and pass the data as props to the Provider.
  • You can pass props to the Provider from server components, but they must be JSON-serializable.
  • You need to split Context and Provider into separate files due to the way that components are dynamically loaded on the client.


The following example shows the implementation of a Provider component:

Next steps