mcpField
S
shopify-hydrogen

shopify-hydrogen

github.com/weaverse开发93154 次安装4 周前更新
代码仓库

关于 shopify-hydrogen

这是一份使用 React Router v7 和 Storefront API 构建 Shopify Hydrogen 店面的参考技能。内容包括 API 指南、离线参考资料，以及搜索 Shopify 实时开发文档的脚本。

主要功能

  1. 01Hydrogen 设置与上下文指南
  2. 02购物车处理器和表单模式
  3. 03缓存策略参考
  4. 04SEO、分页和站点地图指南
  5. 05搜索 Shopify 实时文档

适用场景

  1. 01设置 Hydrogen 服务
  2. 02实现购物车变更
  3. 03选择店面缓存策略
  4. 04查询最新 Hydrogen API

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/weaverse/shopify-hydrogen-skills --skill shopify-hydrogen

安装后在 Claude Code 中输入/shopify-hydrogen确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
01-setup.md
02-caching.md
03-cart.md
04-ssr-performance.md
scripts/
check_docs_helpers.mjs
get_weaverse_page.mjs
search_shopify_docs.mjs
search_weaverse_docs.mjs

详细介绍

Shopify Hydrogen

Hydrogen 是 Shopify 为无头商务打造的主张鲜明的技术栈，基于 React Router v7 构建。它提供实用工具、处理器和组件，帮助你基于 Shopify Storefront API 构建店面。

所有导出均来自 @shopify/hydrogen，该包会重新导出 @shopify/hydrogen-react 中的所有内容。

来源：https://github.com/Shopify/hydrogen/tree/main/packages/hydrogen/src

实时文档

请在此技能自己的文件夹中运行以下命令；下列路径均相对于技能根目录。

如需获取最新的 Hydrogen API 文档，请使用搜索脚本：

node scripts/search_shopify_docs.mjs "<query>"

此脚本会直接查询 Shopify 开发者文档（shopify.dev），并返回最新的 Hydrogen API 参考、代码示例和指南。

示例：

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"

如需离线／缓存参考，请参阅下方的 references/ 文件夹。

核心概念（快速参考）

createHydrogenContext

在 server.ts 中设置所有 Hydrogen 服务的唯一入口。创建并连接 storefront、customerAccount 和 cart。

  • 必需的环境变量：PUBLIC_STORE_DOMAIN、PUBLIC_STOREFRONT_API_TOKEN、PRIVATE_STOREFRONT_API_TOKEN、PUBLIC_STOREFRONT_ID、PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID、SHOP_ID
  • 返回值：{ storefront, customerAccount, cart }
缓存策略
策略maxAgestaleWhileRevalidate适用场景
CacheNone()——用户专属或实时数据
CacheShort()1s9s频繁变化的数据
CacheLong()1hr23hr稳定数据（商店信息、菜单）
CacheCustom({...})customcustom精细控制
购物车处理器

createCartHandler 提供所有购物车操作：get、create、addLines、updateLines、removeLines、updateDiscountCodes、addGiftCardCodes、updateBuyerIdentity、updateNote、setMetafields 等。

CartForm

用于购物车变更的表单组件。使用 CartForm.ACTIONS 枚举（LinesAdd、LinesUpdate、LinesRemove、DiscountCodesUpdate 等），并通过 React Router 的 useFetcher 提交。

useOptimisticCart

在本地应用待处理的购物车变更，以即时反馈 UI。LinesAdd 输入中必须包含 selectedVariant。

分页

使用 getPaginationVariables(request, { pageBy }) 和 <Pagination connection={...}> 组件。GraphQL 查询必须包含 pageInfo { hasPreviousPage hasNextPage startCursor endCursor }。

SEO

getSeoMeta(...) 会生成 React Router meta 数组。支持 title、titleTemplate、description、url、media、jsonLd、robots、alternates。jsonLd 会在各路由之间串接。

站点地图

getSitemapIndex + getSitemap — 两级站点地图生成。需要 Storefront API 2024-10 或更高版本。

内容安全策略

createContentSecurityPolicy({ shop: { checkoutDomain, storeDomain } }) 返回 { nonce, header, NonceProvider }。

参考资料

搜索脚本不可用时，可使用离线／缓存参考资料：

文件内容
references/01-setup.md完整的 server.ts 设置、环境变量、会话、createHydrogenContext 选项
references/02-caching.md缓存策略、AllCacheOptions 类型、generateCacheControlHeader
references/03-cart.md购物车路由设置、CartForm 示例、useOptimisticCart 模式
references/04-ssr-performance.mdSSR 包体精简（worker 会内联动态导入——resolveId 存根模式）、包审计、TTFB 测量方法

评论

支持 Markdown