Using Partial Hydration
Support for Gatsby’s Partial Hydration was added in
email@example.com is currently in Beta.
Partial Hydration enables you to selectively add interactivity to your otherwise completly static app. This results in improved frontend performance while keeping the benefits of client-side apps. Gatsby uses React server components to achieve this.
This guide will explain how you can use Partial Hydration, when and how to declare client components, and which current limitations exist.
We highly recommend reading the Partial Hydration conceptual guide to learn more about how Gatsby uses React server components.
- A Gatsby project set up with
firstname.lastname@example.org later. (Need help creating one? Follow the Quick Start)
react-dom@experimentalinstalled. You can install it like this:
- Enable the
After enabling Partial Hydration all components are server components by default. The generated HTML during
src/pages or via
However, if you need interativity in your components you’ll need to mark them as client components.
To define a component as a client component, you have to use the “use client” directive as the first line of code:
We recommend using server components for everything and to only selectively define client components. There are cases where you need to use client components:
- Interactivity and event listeners (e.g.
- State and lifecycle methods (e.g.
- Browser-only APIs (e.g. accessing properties on
- React Class components
No, you only have to add the “use client” directive to components that are imported into server components. This way you’re setting up a client boundary between server and client components. Therefore client components imported into other client components don’t need the directive. As an example:
- You have an index page at
src/pages/index.jsxthat imports a
<SocialMedia>itself imports an
- By default every component is a server component (as explained above). But
useEffect()so you’ll need to mark a component as a client component.
- You only need to add the “use client” directive to the
<SocialMedia>component since this is the only client component imported into a server component.
Let’s say you have a shared layout component that has an interactive footer to show your latest tweets. Instead of marking the layout component as interactive, you should place the footer into its own component and only mark that component as interactive.
No, you can’t import a server component into a client component. But you can pass a server component as a
children prop to a client component. This way React can instantiate both the client and server components.
children prop to the client component that should contain the server component.
ClientComponent, now pass the server component as a
For the most part, it’s the same as in other parts of your app. However, when sending props from server to client components you need to make sure that the props are serializable. For example, functions or callbacks can’t be passed.
Please note these current limitations:
- The Gatsby Slice API and Partial Hydration are not compatible with each other. When using Partial Hydration you can’t use Gatsby Slices and the other way around.
- You have to use React’s experimental release which we don’t recommend using in production
- A lot of packages in the React ecosystem are not ready for React server components (e.g. CSS-in-JS solutions)
- Partial Hydration only works during
gatsby serve, and not