hydrogen-cms-cli

Add your Hydrogen CMS sections into any Shopify Hydrogen storefront with a single command — just like shadcn/ui.

What it does

You build pages visually in the Hydrogen CMS editor. Your admin assigns you specific sections (Hero, Banner, FAQ, etc.). This CLI:

1. Connects to your CMS backend
2. Checks which sections your admin assigned to you
3. Copies only those section components into your Hydrogen project
4. Generates a ready-to-use CmsRenderer.jsx and fetchCmsPage.js

No config files. No wrappers. You own the code — edit it however you want.

Requirements

• Node.js 18+
• A running Hydrogen CMS backend (your admin gives you the URL)
• Your User ID — visible on the /pages screen of the CMS

Usage

npx hydrogen-cms-cli add --user <YOUR_USER_ID> --api <CMS_API_URL>

Example

npx hydrogen-cms-cli add --user 64abc123def456789 --api https://your-cms-backend.up.railway.app/api

Options

| Flag | Default | Description | |---|---|---| | --user | required | Your CMS User ID | | --api | http://localhost:4000/api | CMS backend API URL | | --out | ./app/cms-sections | Where to write the files |

What gets generated

After running the command, your project will have:

app/cms-sections/
├── CmsRenderer.jsx       ← renders any section by type
├── fetchCmsPage.js       ← fetches published layout from CMS
├── Hero/
│   └── Hero.jsx
├── Banner/
│   └── Banner.jsx
├── FAQ/
│   └── FAQ.jsx
└── ...                   ← only sections your admin assigned to you

How to use in your Hydrogen route

Step 1 — Install socket.io-client (for live preview)

npm install socket.io-client

Step 2 — Use in your route

// app/routes/_index.jsx
import { json } from '@shopify/remix-oxygen'
import { useLoaderData } from '@remix-run/react'
import CmsRenderer from '~/cms-sections/CmsRenderer'
import { fetchCmsPage } from '~/cms-sections/fetchCmsPage'

export async function loader({ context }) {
  // Fetch published layout from CMS
  const { layout } = await fetchCmsPage('home')

  // Fetch real Shopify products (for ProductGrid section)
  const { products } = await context.storefront.query(PRODUCTS_QUERY)

  return json({ layout, products: products.nodes })
}

export default function HomePage() {
  const { layout, products } = useLoaderData()

  return (
    <main>
      <CmsRenderer sections={layout.sections} products={products} />
    </main>
  )
}

const PRODUCTS_QUERY = `#graphql
  query {
    products(first: 12) {
      nodes {
        id handle title
        featuredImage { url altText width height }
        priceRange { minVariantPrice { amount currencyCode } }
      }
    }
  }
`

Step 3 — Add live preview (optional)

See changes from the CMS editor instantly — without page reload:

import { useState, useEffect } from 'react'
import { io } from 'socket.io-client'

const CMS_SOCKET_URL = 'https://your-cms-backend.up.railway.app'
const CMS_USER_ID    = 'YOUR_USER_ID_HERE'

function useLiveCmsPage(initialLayout, slug) {
  const [layout, setLayout] = useState(initialLayout)

  useEffect(() => {
    const s = io(CMS_SOCKET_URL, { withCredentials: true })
    s.emit('join-page', { userId: CMS_USER_ID, slug })
    s.on('draft-update',  ({ layout }) => setLayout(layout))
    s.on('layout-update', ({ layout }) => setLayout(layout))
    return () => s.disconnect()
  }, [slug])

  return layout
}

// In your component:
export default function HomePage() {
  const { layout: initialLayout, products } = useLoaderData()
  const layout = useLiveCmsPage(initialLayout, 'home')

  return (
    <main>
      <CmsRenderer sections={layout.sections} products={products} />
    </main>
  )
}

Available sections

| Section | Type string | Category | |---|---|---| | Hero | Hero | Content | | Banner | Banner | Content | | Rich Text | RichText | Content | | FAQ | FAQ | Content | | Image | Image | Media | | Video | Video | Media | | Product Grid | ProductGrid | Commerce | | Newsletter | Newsletter | Marketing |

Your admin controls which sections you have access to. The CLI only copies what you are allowed to use.

Re-running the CLI

If your admin assigns more sections later, just run the command again:

npx hydrogen-cms-cli add --user <YOUR_USER_ID> --api <CMS_API_URL>

• Already existing files are skipped (not overwritten)
• New sections are added
• CmsRenderer.jsx and fetchCmsPage.js are always regenerated with the latest list

How it works

npx hydrogen-cms-cli add
        │
        ▼
GET /api/public/user-sections/:userId
        │
        ▼
Check which sections are in the CLI registry
        │
        ▼
Copy JSX files → app/cms-sections/
        │
        ▼
Generate CmsRenderer.jsx  (imports + section map)
Generate fetchCmsPage.js  (baked-in userId + API URL)

License

MIT