Hydrogen – Stackbit Docs

Shopify's Hydrogen is a relatively new project at the time of writing.
It heavily utilizes React Server Components, a feature which is still under development by the React core team. Due to the early stage of this framework, a few workarounds were necessary to fully integrate it with Stackbit. Most probably, we'd be able to remove these in the future.

How to use#

Hydrogen is supported through the ssgName: custom option (learn more).

Follow the example repository for a concrete example of integrating Stackbit with a Hydrogen. Here's an excerpt from the Stackbit configuration file:

1
2
3
4
5
6
7
8
9
10
11
12
13

export default {
  stackbitVersion: '~0.6.0',
  cmsName: 'contentful',
  nodeVersion: '16',
  ssgName: 'custom',
  devCommand: 'echo Starting && APP_PORT={PORT} npm run dev-no-window',
  experimental: {
    ssg: {
      name: 'Hydrogen',
      logPatterns: { up: ['Local: http'] },
    },
  },
}

Notes on the above:

In development mode, Hydrogen currently always opens a browser window automatically on startup, which fails when running inside a terminal-only container. Hence, note the npm run dev-no-window script which takes care to work around this behavior.
Usage of the experimental.ssg.logPatterns.up property:
The string 'Local: http' is part of the log message that appears when the Vite dev server is ready to accept requests.
At the time of writing, Hydrogen is not yet based on Vite 3.x and thus HMR is not in effect while a Hydrogen site is open in Stackbit's visual editor.

Content reload#

In the example repository, the main App component includes the StackbitHCR client-side component, which is tasked with capturing on the 'stackbitObjectsChanged' window event.

When a relevant content change is detected, the code utilizes Hydrogen's useServerProps React hook to trigger a refresh to the displayed server-side components.

However, that is not yet a streamlined solution with a stable API. We expect that Hydrogen will provide a clear method for triggering a refresh to server-rendered pages from the client-side

Learn more about listening to content change events.

Managed hosting#

If you're using Managed Hosting you also need to include a Netlify configuration file netlify.toml in your repository. Its contents should look like the following:

[build]
  command = "npm run build"
  publish = "dist/client"

Additionally, Netlify's Hydrogen plugin should be configured in vite.config.js (example).

Example#

Hydrogen Demo Store + Contentful Example
Based on Hydrogen's demo store, with the Journal section modified to fetch data from Contentful rather than Shopify's backend.