Visual editing /Visual Editor /Frameworks /

Use Visual Editor with Hydrogen

Learn how to use Visual Editor with a Hydrogen-based website.

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 Visual Editor. Most probably, we'd be able to remove these in the future.

# Configure Visual Editor for a Hydrogen project

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

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

// stackbit.config.js
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:

  1. 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.
  2. 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.
  3. 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 the visual editor.

# Content reload

In the example repository, the main App component includes the StackbitHCR client-side component, which is tasked with capturing 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.

# 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.