create-oxygen-template 是 Shopify Hydrogen 项目下的技能说明,目标是维护 templates/react-router 作为运行在 Oxygen/MiniOxygen 上、经由 Vite 构建的专业 React Router 起始模板的权威来源。它要求模板与仅限 monorepo 的共享代码和开发期插件解耦,同时通过工作区的 Hydrogen 与 MiniOxygen 包完成本地集成覆盖。
用途与范围:该技能用于创建、升级或维护上述模板,并规定修改模板时应保持应用功能与路由行为不变(除非用户明确要求简化)。实现细节(如 package.json、vite.config.ts、react-router.config.ts、server.ts、entry.server/client、Worker 生命周期、Oxygen 缓存、env 与类型、共享代码迁移的逐文件形态)记录在 reference/react-router-pattern.md 中,需在编写模板文件时阅读该文件。资料也强调这些说明仅适用于 templates/react-router,不应未经补充框架专属指导就套用到 Next/Nuxt/Astro/Solid/SvelteKit。
主要能力与约束:技能列出需要移除的 monorepo 耦合,包括不引入 @shared/、examples/shared/ 运行时依赖、localCdnAssets、@shopify/hydrogen-classic、classic Hydrogen 的 Vite 插件、@react-router/node、@react-router/serve 或 react-router-serve(除非模板有意支持 Node 服务器路径)、Oxygen 上 Hydrogen 原语使用的 lru-cache,以及最终模板 package 中的 catalog: 依赖范围。工作区依赖使用 @shopify/hydrogen: workspace:* 与 @shopify/mini-oxygen: workspace:*,不使用仓库本地 file: 依赖或 vendored 包压缩包。需保留 lib/route-templates.ts 不变,因为它通过 createShopifyRouteTemplates 定义 routeTemplates,而该参数是 handleShopifyRedirects、ShopifyScripts(routes 属性)和 getPredictiveSearchItemUrl(routes 选项)的必需参数。还需添加 Oxygen/MiniOxygen 支持:@shopify/mini-oxygen、@shopify/oxygen-workers-types、仅用于 deploy 脚本的 @shopify/cli(固定 4.6.0,最低 4.4.0,因 deploy 需支持显式 --assets-dir 与 --worker-dir 标志)、Worker 入口(通常为根 server.ts),以及 vite.config.ts 中朴素的 oxygen()(插件在未提供 env 时通过自身 loadEnv 回退自动把 .env 加载进 Worker,需 MiniOxygen >= 4.2.0)。移除 @react-router/node 后必须添加 Workers SSR/客户端入口,否则 react-router typegen/build 会报 “Could not determine server runtime”:app/entry.server.tsx 使用 renderToReadableStream(Web streams,Oxygen 兼容),app/entry.client.tsx 使用 HydratedRouter。运行时层面应将 Oxygen 视为 Worker 运行时:在请求路径内创建请求作用域的 Shopify 原语,通过类型化 app context 传递 env、executionContext、waitUntil 与 cache,避免在运行时依赖 Node 的 process/global 假设,需要共享逻辑时迁移到模板本地文件(通常在 app/lib/ 下)。此外需为真实起始项目重写 README 与 env 文件,并执行 install/typecheck/build/dev/preview 验证。
使用方式(维护者流程):在该仓库中安装需使用 CI=true(无 TTY 时安装会中止并报 ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY),添加模板或变更依赖后的首次安装使用 --no-frozen-lockfile;先运行 pnpm run build:pkgs 构建本地包,因为模板消费 workspace:* 的 Hydrogen 与 MiniOxygen,其运行时导入、打包的 TypeScript 插件、schema 和 Vite 插件使用本仓库构建的包。源码模板声明 "packageManager": "pnpm@10.33.0",不提交模板锁文件(根 .gitignore 排除源码模板锁文件);发行流程会将其改为 "packageManager": "npm@11.17.0",固定 workspace:* 依赖并生成 package-lock.json,Oxygen 的 npm ci 需要该锁文件。验证步骤包括使用 rg 扫描禁用项(排除 pnpm-lock.yaml、package-lock.json、node_modules,避免锁文件中合法的传递依赖造成误报)、运行模板 typecheck(react-router typegen && tsc --noEmit && hydrogen gql check --fail-on-warn)、构建并确认生成 dist/client、dist/server 与 dist/server/index.js、在模板目录运行 node_modules/.bin/shopify hydrogen deploy --help 确认列出 --assets-dir 与 --worker-dir,并实际驱动两种运行时:npm run dev 请求 /、商品页、集合页、/search、/account、/cart 期望 HTTP 200 与实时数据,npm run preview(react-router build && vite preview,需 MiniOxygen >= 4.2.0)通过构建后的 Worker 发起同样请求并确认 .env 已加载。部署方面,README 必须以 Deploy to Oxygen 按钮开头(使用固定的绝对 raw 图片 URL 指向 main 分支,template=react-router 查询参数保持不变),并在 “Deploy to Oxygen” 章节先给出一键流程、再说明手动 npm run deploy 回退;模板 deploy 脚本传入 --assets-dir dist/client --worker-dir dist/server,以选择模板的 react-router 构建输出。技能还要求以 skills/create-oxygen-template 为唯一真源,若通过 .agents 或 .claude 暴露则使用符号链接而非复制目录。
适用场景:面向维护 Shopify Hydrogen 仓库中 React Router + Oxygen 起始模板的开发者,用于模板的新建、依赖升级、去除 monorepo 耦合、补齐 Worker 入口与部署配置、编写 README 与执行发布前验证。
限制与已知环境问题:资料未提供面向终端用户的安装命令、在线演示、收费或价格信息,这些暂未提供。组织环境的 minimumReleaseAge 供应链策略可能拒绝近期发布的传递依赖并导致安装失败,这不是模板缺陷,可选择固定到稳定版本、等待依赖过期或经用户批准以 pnpm install --config.minimumReleaseAge=0 放宽一次;不要与 ERR_PNPM_NO_MATCHING_VERSION 混淆。envFile 弃用警告属正常噪音;macOS 二进制授权(如 Shopify Santa)可能阻止 MiniOxygen 下载的 workerd 二进制,表现为 Vite ready 后崩溃并报 write EPIPE,应先在本地批准 workerd 再判断模板是否有问题。源码模板本身不是独立分发产物,若依赖未发布的 MiniOxygen 行为,需先以 changeset 发布。