Netlify Docs
Ask Netlify

Contact

Netlify Create /Frameworks /

Use Netlify Create with Hydrogen

Learn how to use Netlify Create 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 Netlify Create. Most probably, we'd be able to remove these in the future.

# Configure Netlify Create for a Hydrogen project

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

Follow the example repository for a concrete example of using Netlify Create with Hydrogen. Here's an excerpt from the Netlify Create 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 Netlify Create's 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.

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

# netlify.toml
[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.