shopify-hydrogen
installsforks
How to install shopify-hydrogen?
weaverse/shopify-hydrogen-skills/shopify-hydrogen
$npx -y skills add Weaverse/shopify-hydrogen-skills --skill shopify-hydrogenCore Shopify Hydrogen APIs — createHydrogenContext, cart handler, CartForm, caching strategies, pagination, SEO, variant selection, analytics, and CSP.
SKILL.md
| 1 | # Shopify Hydrogen |
| 2 | |
| 3 | 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. |
| 4 | |
| 5 | **All exports come from `@shopify/hydrogen`**, which re-exports everything from `@shopify/hydrogen-react`. |
| 6 | |
| 7 | > Source: https://github.com/Shopify/hydrogen/tree/main/packages/hydrogen/src |
| 8 | |
| 9 | ## Live Documentation |
| 10 | |
| 11 | For the most up-to-date Hydrogen API docs, use the search script: |
| 12 | |
| 13 | ```bash |
| 14 | node scripts/search_shopify_docs.mjs "<query>" |
| 15 | ``` |
| 16 | |
| 17 | This queries Shopify's developer docs (`shopify.dev`) directly and returns the latest API references, code examples, and guides for Hydrogen. |
| 18 | |
| 19 | **Examples:** |
| 20 | ```bash |
| 21 | node scripts/search_shopify_docs.mjs "createHydrogenContext" |
| 22 | node scripts/search_shopify_docs.mjs "CartForm actions" |
| 23 | node scripts/search_shopify_docs.mjs "caching strategies" |
| 24 | node scripts/search_shopify_docs.mjs "getSeoMeta" |
| 25 | node scripts/search_shopify_docs.mjs "Pagination component" |
| 26 | ``` |
| 27 | |
| 28 | For offline/cached reference, see the [references/](#references) folder below. |
| 29 | |
| 30 | --- |
| 31 | |
| 32 | ## Key Concepts (Quick Reference) |
| 33 | |
| 34 | ### createHydrogenContext |
| 35 | |
| 36 | The single entry point to set up all Hydrogen services in `server.ts`. Creates and wires together `storefront`, `customerAccount`, and `cart`. |
| 37 | |
| 38 | - 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` |
| 39 | - Returns: `{ storefront, customerAccount, cart }` |
| 40 | |
| 41 | ### Caching Strategies |
| 42 | |
| 43 | | Strategy | maxAge | staleWhileRevalidate | Use for | |
| 44 | |----------|--------|----------------------|---------| |
| 45 | | `CacheNone()` | — | — | User-specific or real-time data | |
| 46 | | `CacheShort()` | 1s | 9s | Frequently changing data | |
| 47 | | `CacheLong()` | 1hr | 23hr | Stable data (shop info, menus) | |
| 48 | | `CacheCustom({...})` | custom | custom | Fine-grained control | |
| 49 | |
| 50 | ### Cart Handler |
| 51 | |
| 52 | `createCartHandler` provides all cart operations: `get`, `create`, `addLines`, `updateLines`, `removeLines`, `updateDiscountCodes`, `addGiftCardCodes`, `updateBuyerIdentity`, `updateNote`, `setMetafields`, and more. |
| 53 | |
| 54 | ### CartForm |
| 55 | |
| 56 | Form component for cart mutations. Uses `CartForm.ACTIONS` enum (`LinesAdd`, `LinesUpdate`, `LinesRemove`, `DiscountCodesUpdate`, etc.) and submits via React Router's `useFetcher`. |
| 57 | |
| 58 | ### useOptimisticCart |
| 59 | |
| 60 | Applies pending cart mutations locally for instant UI feedback. Requires `selectedVariant` in `LinesAdd` inputs. |
| 61 | |
| 62 | ### Pagination |
| 63 | |
| 64 | `getPaginationVariables(request, { pageBy })` + `<Pagination connection={...}>` component. GraphQL query must include `pageInfo { hasPreviousPage hasNextPage startCursor endCursor }`. |
| 65 | |
| 66 | ### SEO |
| 67 | |
| 68 | `getSeoMeta(...)` generates React Router `meta` arrays. Supports `title`, `titleTemplate`, `description`, `url`, `media`, `jsonLd`, `robots`, `alternates`. `jsonLd` is concatenated across routes. |
| 69 | |
| 70 | ### Sitemaps |
| 71 | |
| 72 | `getSitemapIndex` + `getSitemap` — two-level sitemap generation. Requires Storefront API 2024-10+. |
| 73 | |
| 74 | ### Content Security Policy |
| 75 | |
| 76 | `createContentSecurityPolicy({ shop: { checkoutDomain, storeDomain } })` returns `{ nonce, header, NonceProvider }`. |
| 77 | |
| 78 | --- |
| 79 | |
| 80 | ## References |
| 81 | |
| 82 | For offline/cached reference when the search script is unavailable: |
| 83 | |
| 84 | | File | Contents | |
| 85 | |------|----------| |
| 86 | | [references/01-setup.md](references/01-setup.md) | Full `server.ts` setup, env vars, session, `createHydrogenContext` options | |
| 87 | | [references/02-caching.md](references/02-caching.md) | Cache strategies, `AllCacheOptions` type, `generateCacheControlHeader` | |
| 88 | | [references/03-cart.md](references/03-cart.md) | Cart route setup, `CartForm` examples, `useOptimisticCart` patterns | |
| 89 | | [references/04-ssr-performance.md](references/04-ssr-performance.md) | SSR bundle diet (worker inlines dynamic imports — `resolveId` stub pattern), bundle audit, TTFB measurement methodology | |
People who liked this also viewed
6 picksType
- hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026
- request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026
- explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026
- ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
