Shopify hydrogen

Skill Weaverse/shopify-hydrogen-skills/skills/shopify-hydrogen

Dedicated agent skills for building, upgrading, and maintaining Shopify Hydrogen storefronts — works with Claude, Cursor, Copilot, and more.

Install

npx -y skills add Weaverse/shopify-hydrogen-skills --skill shopify-hydrogen

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.

What its author says it does

Copied from the file, not written here

Core Shopify Hydrogen APIs — createHydrogenContext, cart handler, CartForm, caching strategies, pagination, SEO, variant selection, analytics, and CSP.

SKILL.md

4.0 KB, as published. Nobody here has run it

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

For the most up-to-date Hydrogen API docs, use the search script:

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

node 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