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
fetchthat 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.
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:
App.server.jsxrelies on the
pagestate to choose the correct route to render. To change routes, the client updates the
pagestate is sent to the server. This happens through a
useServerResponsefetch call. It's a special server endpoint called
stateas a query parameter.
/reactendpoint returns the wire representation for the new state.
The state is partially hydrated (made interactive) and rendered into the DOM, similar to how the initial page was made interactive.
/react for routing, but also for any other state that needs to be synced to the server.
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.
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
- You can't fetch server-only data from within
Providercomponents. Instead, fetch data within server components and pass the data as props to the
- You can pass props to the
Providerfrom server components, but they must be JSON-serializable.
- You need to split
Providerinto separate files due to the way that components are dynamically loaded on the client.
The following example shows the implementation of a