Shopify Hydrogen
Hydrogen is Shopify's opinionated stack for headless commerce, built on React Router v7. It provides utilities, handlers, and components for building storefronts on top of the Shopify Storefront API.
All exports come from @shopify/hydrogen, which re-exports everything from @shopify/hydrogen-react.
Source: https://github.com/Shopify/hydrogen/tree/main/packages/hydrogen/src
Live Documentation
Run these from this skill's own folder; the paths below are relative to the skill root.
For the most up-to-date Hydrogen API docs, use the search script:
bashnode scripts/search_shopify_docs.mjs "<query>"
This queries Shopify's developer docs (shopify.dev) directly and returns the latest API references, code examples, and guides for Hydrogen.
Examples:
bashnode scripts/search_shopify_docs.mjs "createHydrogenContext" node scripts/search_shopify_docs.mjs "CartForm actions" node scripts/search_shopify_docs.mjs "caching strategies" node scripts/search_shopify_docs.mjs "getSeoMeta" node scripts/search_shopify_docs.mjs "Pagination component"
For offline/cached reference, see the references/ folder below.
Key Concepts (Quick Reference)
createHydrogenContext
The single entry point to set up all Hydrogen services in server.ts. Creates and wires together storefront, customerAccount, and cart.
- Required env vars:
PUBLIC_STORE_DOMAIN,PUBLIC_STOREFRONT_API_TOKEN,PRIVATE_STOREFRONT_API_TOKEN,PUBLIC_STOREFRONT_ID,PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID,SHOP_ID - Returns:
{ storefront, customerAccount, cart }
Caching Strategies
| Strategy | maxAge | staleWhileRevalidate | Use for |
|---|---|---|---|
CacheNone() | — | — | User-specific or real-time data |
CacheShort() | 1s | 9s | Frequently changing data |
CacheLong() | 1hr | 23hr | Stable data (shop info, menus) |
CacheCustom({...}) | custom | custom | Fine-grained control |
Cart Handler
createCartHandler provides all cart operations: get, create, addLines, updateLines, removeLines, updateDiscountCodes, addGiftCardCodes, updateBuyerIdentity, updateNote, setMetafields, and more.
CartForm
Form component for cart mutations. Uses CartForm.ACTIONS enum (LinesAdd, LinesUpdate, LinesRemove, DiscountCodesUpdate, etc.) and submits via React Router's useFetcher.
useOptimisticCart
Applies pending cart mutations locally for instant UI feedback. Requires selectedVariant in LinesAdd inputs.
Pagination
getPaginationVariables(request, { pageBy }) + <Pagination connection={...}> component. GraphQL query must include pageInfo { hasPreviousPage hasNextPage startCursor endCursor }.
SEO
getSeoMeta(...) generates React Router meta arrays. Supports title, titleTemplate, description, url, media, jsonLd, robots, alternates. jsonLd is concatenated across routes.
Sitemaps
getSitemapIndex + getSitemap — two-level sitemap generation. Requires Storefront API 2024-10+.
Content Security Policy
createContentSecurityPolicy({ shop: { checkoutDomain, storeDomain } }) returns { nonce, header, NonceProvider }.
References
For offline/cached reference when the search script is unavailable:
| File | Contents |
|---|---|
| references/01-setup.md | Full server.ts setup, env vars, session, createHydrogenContext options |
| references/02-caching.md | Cache strategies, AllCacheOptions type, generateCacheControlHeader |
| references/03-cart.md | Cart route setup, CartForm examples, useOptimisticCart patterns |
| references/04-ssr-performance.md | SSR bundle diet (worker inlines dynamic imports — resolveId stub pattern), bundle audit, TTFB measurement methodology |
