Shopify Hydrogen Patterns (Headless)

Patterns pour Hydrogen 2024+, le framework headless officiel Shopify basé sur Remix + Vite, déployé sur Oxygen (CDN edge Shopify).

Attention : Hydrogen a changé d'architecture en 2023 (ancien Hydrogen 1 sur Vite custom → Hydrogen 2+ sur Remix + Vite standard). Tout le code ancien est obsolète.

Structure d'un projet Hydrogen

hydrogen-storefront/
├── app/
│   ├── root.tsx                  # Layout racine + meta + links
│   ├── entry.client.tsx          # Hydration client
│   ├── entry.server.tsx          # SSR Remix
│   ├── components/
│   │   ├── Header.tsx
│   │   ├── Footer.tsx
│   │   ├── ProductCard.tsx
│   │   └── Cart.tsx
│   ├── routes/
│   │   ├── _index.tsx            # Homepage
│   │   ├── products.$handle.tsx  # Product page
│   │   ├── collections.$handle.tsx
│   │   ├── cart.tsx
│   │   ├── account.tsx
│   │   └── api.*.tsx             # API routes
│   ├── lib/
│   │   ├── fragments.ts          # Fragments GraphQL partagés
│   │   ├── session.server.ts     # Session management
│   │   └── seo.ts
│   └── styles/
├── public/
├── server.ts                     # Oxygen entry point
├── vite.config.ts
├── tsconfig.json
└── package.json

Création d'un projet

npm create @shopify/hydrogen@latest
# Choisir : JavaScript ou TypeScript, starter, routing, i18n

Loader avec Storefront API

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

const PRODUCT_QUERY = `#graphql
  query Product($handle: String!, $country: CountryCode, $language: LanguageCode)
    @inContext(country: $country, language: $language) {
    product(handle: $handle) {
      id
      title
      vendor
      handle
      descriptionHtml
      featuredImage {
        url
        altText
        width
        height
      }
      priceRange {
        minVariantPrice { amount currencyCode }
        maxVariantPrice { amount currencyCode }
      }
      variants(first: 100) {
        nodes {
          id
          title
          availableForSale
          selectedOptions { name value }
          image { url altText }
          price { amount currencyCode }
          compareAtPrice { amount currencyCode }
        }
      }
      seo { title description }
    }
  }
`;

export async function loader({ params, context }: LoaderFunctionArgs) {
  const { handle } = params;
  if (!handle) throw new Response("Missing handle", { status: 400 });

  const { product } = await context.storefront.query(PRODUCT_QUERY, {
    variables: {
      handle,
      country: context.storefront.i18n.country,
      language: context.storefront.i18n.language,
    },
    cache: context.storefront.CacheLong(),
  });

  if (!product) {
    throw new Response("Product not found", { status: 404 });
  }

  return json({ product });
}

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

  return (
    <article>
      <h1>{product.title}</h1>
      {product.featuredImage && (
        <img
          src={product.featuredImage.url}
          alt={product.featuredImage.altText ?? product.title}
          width={product.featuredImage.width}
          height={product.featuredImage.height}
          loading="eager"
        />
      )}
      {/*
        Rendre product.descriptionHtml requiert une sanitization côté serveur.
        Option 1 : pré-sanitizer avec DOMPurify côté loader avant json().
        Option 2 : utiliser @shopify/hydrogen <RichText /> qui sanitize.
        Ne jamais injecter descriptionHtml brut dans le DOM sans filtre.
      */}
      {/* Variant picker + add-to-cart ici */}
    </article>
  );
}

Cart management

// app/routes/cart.tsx
import { json, type ActionFunctionArgs } from "@shopify/remix-oxygen";
import { CartForm, type CartQueryDataReturn } from "@shopify/hydrogen";

export async function action({ request, context }: ActionFunctionArgs) {
  const { cart } = context;
  const formData = await request.formData();

  const { action: cartAction, inputs } = CartForm.getFormInput(formData);

  let result: CartQueryDataReturn;

  switch (cartAction) {
    case CartForm.ACTIONS.LinesAdd:
      result = await cart.addLines(inputs.lines);
      break;
    case CartForm.ACTIONS.LinesUpdate:
      result = await cart.updateLines(inputs.lines);
      break;
    case CartForm.ACTIONS.LinesRemove:
      result = await cart.removeLines(inputs.lineIds);
      break;
    default:
      throw new Error(`Unknown cart action ${cartAction}`);
  }

  const { cart: updatedCart, errors } = result;

  return json({ cart: updatedCart, errors });
}

Usage côté UI :

// app/components/AddToCartButton.tsx
import { CartForm } from "@shopify/hydrogen";

export function AddToCartButton({ variantId }: { variantId: string }) {
  return (
    <CartForm
      route="/cart"
      action={CartForm.ACTIONS.LinesAdd}
      inputs={{ lines: [{ merchandiseId: variantId, quantity: 1 }] }}
    >
      {(fetcher) => (
        <button
          type="submit"
          disabled={fetcher.state !== "idle"}
        >
          {fetcher.state !== "idle" ? "Adding..." : "Add to cart"}
        </button>
      )}
    </CartForm>
  );
}

Customer Account API (auth moderne)

Hydrogen 2024 utilise le nouveau Customer Account API (pas l'ancien Storefront Customer API). Il fournit une UX d'authentification gérée par Shopify (OTP email/SMS, pas de mot de passe côté storefront).

// app/routes/account.tsx
import { json, redirect, type LoaderFunctionArgs } from "@shopify/remix-oxygen";

export async function loader({ context }: LoaderFunctionArgs) {
  const { customerAccount } = context;

  if (!(await customerAccount.isLoggedIn())) {
    return redirect("/account/login");
  }

  const { data } = await customerAccount.query(`#graphql
    query Customer {
      customer {
        id
        firstName
        lastName
        emailAddress { emailAddress }
        defaultAddress { formatted }
      }
    }
  `);

  return json({ customer: data.customer });
}

Caching strategy

// CacheShort : 1 seconde (dev, volatile data)
cache: context.storefront.CacheShort();

// CacheLong : 1 heure (produits, collections stables)
cache: context.storefront.CacheLong();

// CacheCustom : custom max-age + stale-while-revalidate
cache: context.storefront.CacheCustom({
  mode: "public",
  maxAge: 60 * 5,           // 5 min
  staleWhileRevalidate: 60, // 1 min
});

// Pas de cache : données dynamiques (cart, customer)
cache: context.storefront.CacheNone();

Règle : produits et collections → CacheLong. Cart et customer → CacheNone. Homepage → CacheCustom (mix).

Image optimization (Shopify CDN)

import { Image } from "@shopify/hydrogen";

<Image
  data={product.featuredImage}
  aspectRatio="1/1"
  sizes="(min-width: 1024px) 33vw, 100vw"
  loading="lazy"
/>

Hydrogen utilise automatiquement le CDN Shopify pour :

• Responsive srcset multi-résolutions
• Format WebP/AVIF selon le navigateur
• LQIP (low quality image placeholder)

i18n — Markets et currencies

// app/lib/i18n.ts
export const COUNTRIES = {
  default: { label: "United States", language: "EN", country: "US", currency: "USD" },
  fr: { label: "France", language: "FR", country: "FR", currency: "EUR" },
  de: { label: "Germany", language: "DE", country: "DE", currency: "EUR" },
};

export function getLocaleFromRequest(request: Request): I18nLocale {
  const url = new URL(request.url);
  const firstPathPart = url.pathname.split("/")[1];
  return COUNTRIES[firstPathPart] ?? COUNTRIES.default;
}

Toutes les requêtes Storefront API doivent passer country et language dans @inContext(...) pour que Shopify retourne les bons prix/traductions.

Déploiement Oxygen

# Login Shopify Partners
npm run shopify hydrogen login

# Lier à un store
npm run shopify hydrogen link

# Déployer
npm run shopify hydrogen deploy

# Preview local
npm run dev

Oxygen gère automatiquement :

• Edge deployment sur 200+ PoPs
• Environnements (production, preview, dev)
• Variables d'environnement via Partner Dashboard
• Zero-downtime deploys

Performance checklist

• Lighthouse mobile ≥ 90 sur product page et homepage
• LCP < 2s (image héro preloadée + loading="eager")
• CLS < 0.1 (dimensions images définies, fonts via font-display: swap)
• TBT < 200ms (pas de blocking JS)
• Cache headers corrects sur chaque route via CacheShort/Long/Custom
• Streaming Remix pour les loaders non-critiques via defer()

Anti-patterns Hydrogen

1. Utiliser l'ancien Hydrogen 1 (Vite custom) → migrer vers Hydrogen 2+ (Remix)
2. Storefront API sur du customer data → utiliser Customer Account API
3. <img> brut sans le composant <Image> de @shopify/hydrogen
4. Hardcoder country / language → toujours dériver de la locale (URL segment)
5. Pas de @inContext dans les queries → prix et traductions incorrects par marché
6. Cart mutation sans CartForm → perte d'optimistic UI + error handling
7. Secrets dans .env local committé → toujours via Oxygen environment variables
8. Images sans dimensions → CLS catastrophique
9. Injecter descriptionHtml sans sanitization → XSS : utiliser un composant <RichText /> Hydrogen ou pré-sanitizer côté loader avec DOMPurify

SEO pattern

// app/routes/products.$handle.tsx
import type { MetaFunction } from "@shopify/remix-oxygen";

export const meta: MetaFunction<typeof loader> = ({ data }) => {
  if (!data?.product) return [];
  return [
    { title: data.product.seo.title ?? data.product.title },
    { name: "description", content: data.product.seo.description ?? "" },
    {
      tagName: "link",
      rel: "canonical",
      href: `https://example.com/products/${data.product.handle}`,
    },
    {
      "script:ld+json": {
        "@context": "https://schema.org",
        "@type": "Product",
        name: data.product.title,
        description: data.product.seo.description,
        brand: { "@type": "Brand", name: data.product.vendor },
        offers: {
          "@type": "Offer",
          price: data.product.priceRange.minVariantPrice.amount,
          priceCurrency: data.product.priceRange.minVariantPrice.currencyCode,
          availability: "https://schema.org/InStock",
        },
      },
    },
  ];
};

Quand utiliser ce skill vs déléguer

• Hydrogen spécifique (loaders, cart, Customer Account, Oxygen) → ce skill
• React/Remix générique → atum-stack-web (nextjs-expert ou remix patterns génériques)
• Theming Liquid OS 2.0 → skill shopify-liquid-patterns (dans ce plugin)
• Expertise dense Shopify → agent shopify-expert (dans ce plugin)
• Audit sécurité → security-reviewer

Ressources

• Hydrogen docs — https://shopify.dev/docs/storefronts/headless/hydrogen
• Hydrogen API reference — https://shopify.dev/docs/api/hydrogen
• Storefront API — https://shopify.dev/docs/api/storefront
• Customer Account API — https://shopify.dev/docs/api/customer
• Oxygen deployment — https://shopify.dev/docs/custom-storefronts/oxygen