Partial Hydration in Gatsby: A Performance-Boosting Feature

What is Partial Hydration?

Partial hydration in Gatsby is a feature that allows you to selectively hydrate client components on the server, while still keeping the benefits of client-side apps. This approach can lead to improved frontend performance and faster page loads.

Enabling Partial Hydration

To use partial hydration in Gatsby, you need to enable the PARTIAL_HYDRATION flag in the gatsby-config file. Then, you can mark specific components as “use client” to indicate that they should be hydrated on the client-side.

Known Issues and Limitations

Some known issues with partial hydration include:

• Styling libraries like emotion and styled-components do not currently work when partial hydration is enabled.
• React Server Components is not supported.
• gatsby-plugin-offline is not supported and may cause build failures.

Using Partial Hydration

Partial hydration is still in beta and has some limitations. However, it can provide significant performance improvements for pages with interactive components.

To get started with partial hydration, follow these steps:

1. Install the latest version of Gatsby and experimental versions of React and react-dom.
2. Enable the PARTIAL_HYDRATION flag in the gatsby-config file.
3. Mark specific components as “use client” to indicate that they should be hydrated on the client-side.

Example Code

Here’s an example of how to use partial hydration in Gatsby:

// src/components/demo.js
import React from 'eact';

const Demo = () => {
  const [count, setCount] = React.useState(0);

  return (
    <div>
      Count: {count}
      <br />
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
};

export default Demo;

// src/pages/using-partial-hydration.js
import React from 'eact';
import Demo from '../components/demo';

const Page = () => {
  return (
    <div>
      Welcome to my page!
      <br />
      <Demo />
    </div>
  );
};

export default Page;

By marking the Demo component as “use client”, we’re telling Gatsby to hydrate it on the client-side, while still keeping the benefits of server-side rendering for the rest of the page.

For more information about partial hydration with Gatsby 5, check out the RFC and the conceptual guide.