{"id":"ab2216de-dbd8-47d6-85b3-5ecb486caf90","shortId":"vWy2DJ","kind":"skill","title":"shopify-hydrogen","tagline":"Core Shopify Hydrogen APIs — createHydrogenContext, cart handler, CartForm, caching strategies, pagination, SEO, variant selection, analytics, and CSP.","description":"# Shopify Hydrogen\n\nHydrogen 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.\n\n**All exports come from `@shopify/hydrogen`**, which re-exports everything from `@shopify/hydrogen-react`.\n\n> Source: https://github.com/Shopify/hydrogen/tree/main/packages/hydrogen/src\n\n## Live Documentation\n\nFor the most up-to-date Hydrogen API docs, use the search script:\n\n```bash\nnode scripts/search_shopify_docs.mjs \"<query>\"\n```\n\nThis queries Shopify's developer docs (`shopify.dev`) directly and returns the latest API references, code examples, and guides for Hydrogen.\n\n**Examples:**\n```bash\nnode scripts/search_shopify_docs.mjs \"createHydrogenContext\"\nnode scripts/search_shopify_docs.mjs \"CartForm actions\"\nnode scripts/search_shopify_docs.mjs \"caching strategies\"\nnode scripts/search_shopify_docs.mjs \"getSeoMeta\"\nnode scripts/search_shopify_docs.mjs \"Pagination component\"\n```\n\nFor offline/cached reference, see the [references/](#references) folder below.\n\n---\n\n## Key Concepts (Quick Reference)\n\n### createHydrogenContext\n\nThe single entry point to set up all Hydrogen services in `server.ts`. Creates and wires together `storefront`, `customerAccount`, and `cart`.\n\n- 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`\n- Returns: `{ storefront, customerAccount, cart }`\n\n### Caching Strategies\n\n| Strategy | maxAge | staleWhileRevalidate | Use for |\n|----------|--------|----------------------|---------|\n| `CacheNone()` | — | — | User-specific or real-time data |\n| `CacheShort()` | 1s | 9s | Frequently changing data |\n| `CacheLong()` | 1hr | 23hr | Stable data (shop info, menus) |\n| `CacheCustom({...})` | custom | custom | Fine-grained control |\n\n### Cart Handler\n\n`createCartHandler` provides all cart operations: `get`, `create`, `addLines`, `updateLines`, `removeLines`, `updateDiscountCodes`, `addGiftCardCodes`, `updateBuyerIdentity`, `updateNote`, `setMetafields`, and more.\n\n### CartForm\n\nForm component for cart mutations. Uses `CartForm.ACTIONS` enum (`LinesAdd`, `LinesUpdate`, `LinesRemove`, `DiscountCodesUpdate`, etc.) and submits via React Router's `useFetcher`.\n\n### useOptimisticCart\n\nApplies pending cart mutations locally for instant UI feedback. Requires `selectedVariant` in `LinesAdd` inputs.\n\n### Pagination\n\n`getPaginationVariables(request, { pageBy })` + `<Pagination connection={...}>` component. GraphQL query must include `pageInfo { hasPreviousPage hasNextPage startCursor endCursor }`.\n\n### SEO\n\n`getSeoMeta(...)` generates React Router `meta` arrays. Supports `title`, `titleTemplate`, `description`, `url`, `media`, `jsonLd`, `robots`, `alternates`. `jsonLd` is concatenated across routes.\n\n### Sitemaps\n\n`getSitemapIndex` + `getSitemap` — two-level sitemap generation. Requires Storefront API 2024-10+.\n\n### Content Security Policy\n\n`createContentSecurityPolicy({ shop: { checkoutDomain, storeDomain } })` returns `{ nonce, header, NonceProvider }`.\n\n---\n\n## References\n\nFor offline/cached reference when the search script is unavailable:\n\n| File | Contents |\n|------|----------|\n| [references/01-setup.md](references/01-setup.md) | Full `server.ts` setup, env vars, session, `createHydrogenContext` options |\n| [references/02-caching.md](references/02-caching.md) | Cache strategies, `AllCacheOptions` type, `generateCacheControlHeader` |\n| [references/03-cart.md](references/03-cart.md) | Cart route setup, `CartForm` examples, `useOptimisticCart` patterns |","tags":["shopify","hydrogen","skills","weaverse","agent-skills","agentic-commerce","shopify-hydrogen","shopify-hydrogen-skills","weaverse-hydrogen"],"capabilities":["skill","source-weaverse","skill-shopify-hydrogen","topic-agent-skills","topic-agentic-commerce","topic-shopify-hydrogen","topic-shopify-hydrogen-skills","topic-weaverse-hydrogen"],"categories":["shopify-hydrogen-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/Weaverse/shopify-hydrogen-skills/shopify-hydrogen","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add Weaverse/shopify-hydrogen-skills","source_repo":"https://github.com/Weaverse/shopify-hydrogen-skills","install_from":"skills.sh"}},"qualityScore":"0.466","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 33 github stars · SKILL.md body (3,664 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-01T12:57:20.929Z","embedding":null,"createdAt":"2026-04-18T22:21:47.243Z","updatedAt":"2026-05-01T12:57:20.929Z","lastSeenAt":"2026-05-01T12:57:20.929Z","tsv":"'-10':332 '/shopify/hydrogen/tree/main/packages/hydrogen/src':68 '1hr':214 '1s':208 '2024':331 '23hr':215 '9s':209 'account':181 'across':318 'action':116 'addgiftcardcod':241 'addlin':237 'allcacheopt':370 'altern':314 'analyt':18 'api':7,52,79,100,170,174,182,330 'appli':269 'array':305 'bash':85,109 'build':44 'built':32 'cach':12,119,191,368 'cachecustom':221 'cachelong':213 'cachenon':198 'cacheshort':207 'cart':9,161,190,228,233,251,271,375 'cartform':11,115,247,378 'cartform.actions':254 'chang':211 'checkoutdomain':338 'client':183 'code':102 'come':55 'commerc':31 'compon':42,127,249,289 'concaten':317 'concept':138 'connect':288 'content':333,355 'control':227 'core':4 'creat':154,236 'createcarthandl':230 'createcontentsecuritypolici':336 'createhydrogencontext':8,112,141,364 'csp':20 'custom':180,222,223 'customeraccount':159,189 'data':206,212,217 'date':77 'descript':309 'develop':92 'direct':95 'discountcodesupd':259 'doc':80,93 'document':70 'domain':167 'endcursor':298 'entri':144 'enum':255 'env':163,361 'etc':260 'everyth':62 'exampl':103,108,379 'export':54,61 'feedback':277 'file':354 'fine':225 'fine-grain':224 'folder':135 'form':248 'frequent':210 'full':358 'generat':301,327 'generatecachecontrolhead':372 'get':235 'getpaginationvari':284 'getseometa':123,300 'getsitemap':322 'getsitemapindex':321 'github.com':67 'github.com/shopify/hydrogen/tree/main/packages/hydrogen/src':66 'grain':226 'graphql':290 'guid':105 'handler':10,40,229 'hasnextpag':296 'haspreviouspag':295 'header':342 'headless':30 'hydrogen':3,6,22,23,78,107,150 'id':178,184,186 'includ':293 'info':219 'input':282 'instant':275 'jsonld':312,315 'key':137 'latest':99 'level':325 'linesadd':256,281 'linesremov':258 'linesupd':257 'live':69 'local':273 'maxag':194 'media':311 'menus':220 'meta':304 'must':292 'mutat':252,272 'node':86,110,113,117,121,124 'nonc':341 'nonceprovid':343 'offline/cached':129,346 'oper':234 'opinion':27 'option':365 'pagebi':286 'pageinfo':294 'pagin':14,126,283,287 'pattern':381 'pend':270 'point':145 'polici':335 'privat':172 'provid':38,231 'public':165,168,176,179 'queri':89,291 'quick':139 're':60 're-export':59 'react':34,264,302 'real':204 'real-tim':203 'refer':101,130,133,134,140,344,347 'references/01-setup.md':356,357 'references/02-caching.md':366,367 'references/03-cart.md':373,374 'removelin':239 'request':285 'requir':162,278,328 'return':97,187,340 'robot':313 'rout':319,376 'router':35,265,303 'script':84,351 'scripts/search_shopify_docs.mjs':87,111,114,118,122,125 'search':83,350 'secur':334 'see':131 'select':17 'selectedvari':279 'seo':15,299 'server.ts':153,359 'servic':151 'session':363 'set':147 'setmetafield':244 'setup':360,377 'shop':185,218,337 'shopifi':2,5,21,25,50,90 'shopify-hydrogen':1 'shopify.dev':94 'shopify/hydrogen':57 'shopify/hydrogen-react':64 'singl':143 'sitemap':320,326 'skill' 'skill-shopify-hydrogen' 'sourc':65 'source-weaverse' 'specif':201 'stabl':216 'stack':28 'stalewhilerevalid':195 'startcursor':297 'store':166 'storedomain':339 'storefront':45,51,158,169,173,177,188,329 'strategi':13,120,192,193,369 'submit':262 'support':306 'time':205 'titl':307 'titletempl':308 'togeth':157 'token':171,175 'top':47 'topic-agent-skills' 'topic-agentic-commerce' 'topic-shopify-hydrogen' 'topic-shopify-hydrogen-skills' 'topic-weaverse-hydrogen' 'two':324 'two-level':323 'type':371 'ui':276 'unavail':353 'up-to-d':74 'updatebuyerident':242 'updatediscountcod':240 'updatelin':238 'updatenot':243 'url':310 'use':81,196,253 'usefetch':267 'useoptimisticcart':268,380 'user':200 'user-specif':199 'util':39 'v7':36 'var':164,362 'variant':16 'via':263 'wire':156","prices":[{"id":"77cae433-a78e-43af-9243-fc13aa0363c8","listingId":"ab2216de-dbd8-47d6-85b3-5ecb486caf90","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"Weaverse","category":"shopify-hydrogen-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:21:47.243Z"}],"sources":[{"listingId":"ab2216de-dbd8-47d6-85b3-5ecb486caf90","source":"github","sourceId":"Weaverse/shopify-hydrogen-skills/shopify-hydrogen","sourceUrl":"https://github.com/Weaverse/shopify-hydrogen-skills/tree/main/skills/shopify-hydrogen","isPrimary":false,"firstSeenAt":"2026-04-18T22:21:47.243Z","lastSeenAt":"2026-05-01T12:57:20.929Z"}],"details":{"listingId":"ab2216de-dbd8-47d6-85b3-5ecb486caf90","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Weaverse","slug":"shopify-hydrogen","github":{"repo":"Weaverse/shopify-hydrogen-skills","stars":33,"topics":["agent-skills","agentic-commerce","shopify-hydrogen","shopify-hydrogen-skills","weaverse-hydrogen"],"license":null,"html_url":"https://github.com/Weaverse/shopify-hydrogen-skills","pushed_at":"2026-04-24T10:12:43Z","description":"Dedicated agent skills for building, upgrading, and maintaining Shopify Hydrogen storefronts — works with Claude, Cursor, Copilot, and more.","skill_md_sha":"2dddabc43e5503db24b879447e54503340994647","skill_md_path":"skills/shopify-hydrogen/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/Weaverse/shopify-hydrogen-skills/tree/main/skills/shopify-hydrogen"},"layout":"multi","source":"github","category":"shopify-hydrogen-skills","frontmatter":{"name":"shopify-hydrogen","description":"Core Shopify Hydrogen APIs — createHydrogenContext, cart handler, CartForm, caching strategies, pagination, SEO, variant selection, analytics, and CSP."},"skills_sh_url":"https://skills.sh/Weaverse/shopify-hydrogen-skills/shopify-hydrogen"},"updatedAt":"2026-05-01T12:57:20.929Z"}}