headless-hydrogen

Headless Commerce with Hydrogen

When to use this skill

Use this skill when:

• Building a custom headless storefront
• Using Hydrogen framework for e-commerce
• Deploying to Oxygen (Shopify's edge hosting)
• Working with the Storefront API
• Creating high-performance, custom storefronts
• Integrating Shopify with custom tech stacks

What is Hydrogen?

Hydrogen is Shopify's official headless commerce framework built on:

• React Router - For routing and data loading
• React - Component-based UI
• GraphQL - Data fetching from Storefront API
• Oxygen - Global edge deployment (free hosting)

Key Benefits

• Build-ready components - Pre-built commerce components
• Free hosting - Deploy to Oxygen at no extra cost
• Fast by default - SSR, progressive enhancement, nested routes
• Shopify-native - Deep integration with Shopify APIs

Getting Started

1. Create a Hydrogen App

# Create new Hydrogen project
npm create @shopify/hydrogen@latest

# Follow the prompts:
# - Choose a template (Demo store, Hello World, Skeleton)
# - Enter your store URL
# - Select JavaScript or TypeScript

2. Project Structure

hydrogen-app/
├── app/
│   ├── components/        # React components
│   ├── routes/            # Page routes
│   │   ├── _index.tsx     # Home page
│   │   ├── products.$handle.tsx  # Product page
│   │   └── collections.$handle.tsx
│   ├── styles/            # CSS files
│   ├── entry.client.tsx   # Client entry
│   └── entry.server.tsx   # Server entry
├── public/                # Static assets
├── .env                   # Environment variables
├── hydrogen.config.ts     # Hydrogen config
└── package.json

3. Environment Setup

# .env
SESSION_SECRET=your-session-secret
PUBLIC_STOREFRONT_API_TOKEN=your-storefront-api-token
PUBLIC_STORE_DOMAIN=your-store.myshopify.com

4. Start Development

npm run dev

Core Concepts

Routes and Data Loading

// app/routes/products.$handle.tsx
import { useLoaderData, type LoaderFunctionArgs } from "@remix-run/react";

export async function loader({ params, context }: LoaderFunctionArgs) {
  const { storefront } = context;
  const { handle } = params;

  const { product } = await storefront.query(PRODUCT_QUERY, {
    variables: { handle },
  });

  if (!product) {
    throw new Response("Not Found", { status: 404 });
  }

  return { product };
}

export default function ProductPage() {
  const { product } = useLoaderData<typeof loader>();

  return (
    <div className="product-page">
      <h1>{product.title}</h1>
      <p>{product.description}</p>
      <ProductPrice data={product} />
      <AddToCartButton variantId={product.variants.nodes[0].id} />
    </div>
  );
}

const PRODUCT_QUERY = `#graphql
  query Product($handle: String!) {
    product(handle: $handle) {
      id
      title
      description
      handle
      variants(first: 1) {
        nodes {
          id
          price {
            amount
            currencyCode
          }
        }
      }
      featuredImage {
        url
        altText
      }
    }
  }
`;