在 Shopify Hydrogen 无头电商中集成 Builder.ioSkeleton 模板实战指南【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builderHydrogen 是 Shopify 面向无头商务headless commerce推出的技术栈专门设计与 Shopify 的全栈 Web 框架 Remix 深度配合。本仓库中的 Hydrogen 示例位于 packages/sdks/snippets/hydrogen在官方 Skeleton 模板之上用最小化的组件、查询与工具链演示了如何把 Builder.io 的可视化开发能力接入 Hydrogen 应用。读完本文你将掌握 Hydrogen Skeleton 模板的初始化、本地开发与生产构建流程理解 Storefront / Customer Account / Cart 三套客户端在服务端入口中的装配方式并能在 Hydrogen 的 Remix 路由中落地 Builder.io 的fetchOneEntryContent渲染管线。模板定位为无头商务而生的最小化起点官方 Skeleton 模板的核心设计哲学是最小化只包含跑通一条完整链路所必需的组件、查询与工具而不是一个功能堆砌的巨型脚手架。其技术底座包含Remix全栈 Web 框架负责路由、加载器与数据流编排HydrogenShopify 官方无头商务 SDK提供 Storefront、Customer Account、Cart 等客户端OxygenShopify 的托管运行时让应用以 Worker 形态部署Vite构建与开发服务器Shopify CLI开发、构建、预览与代码生成的一站式命令行工具ESLint 与 Prettier代码质量与格式规范GraphQL generator由 Storefront 与 Customer Account API 的 GraphQL Schema 自动生成类型TypeScript 与 JavaScript 双风味同一套模板可选择 TS 或 JS 起步最小化的组件与路由集便于在此基础上快速扩展。在本仓库中这套模板还被注入了 Builder.io 的 React SDKbuilder.io/sdk-react从而把可视化页面搭建能力嵌入无头电商站点这也正是该示例在builder项目中的独特价值所在。环境要求与项目初始化官方模板要求Node.js 18.0.0 或更高版本。初始化一个新项目只需一条命令npm create shopify/hydrogenlatest如果你希望在现有 Builder.io 仓库中直接研究或复用这套配置本示例的完整源码位于 packages/sdks/snippets/hydrogen其package.json中声明的核心依赖包括builder.io/sdk-react工作区引用、shopify/hydrogen2024.4.x、shopify/remix-oxygen、remix-run/react、shopify/cli-hydrogen以及graphql所有依赖都锁定在 package.json 中可直接安装运行。目录结构与工程布局模板采用 Remix 约定式路由配合 Hydrogen 的服务端入口与 Builder.io 的按模型model拆分组件packages/sdks/snippets/hydrogen/ ├── app/ │ ├── components/ # Builder 模型对应的页面组件 │ ├── graphql/ # Customer Account API 的查询与变更 │ ├── lib/ # fragments、session、variants、root-data 等 │ ├── routes/ # Remix 路由含 Builder 相关路由 │ ├── styles/ # reset.css / app.css │ ├── entry.client.tsx # 浏览器端入口 │ ├── entry.server.tsx # 服务端渲染入口含 CSP │ └── root.tsx # 根布局与错误边界 ├── server.ts # Worker fetch 入口装配三大客户端 ├── vite.config.ts # Hydrogen Oxygen Remix tsconfigPaths ├── storefrontapi.generated.d.ts ├── customer-accountapi.generated.d.ts └── package.jsonvite.config.ts是理解构建链的关键它依次挂载了hydrogen()、oxygen()、remix()使用hydrogen.preset()预设并开启了v3_fetcherPersist、v3_relativeSplatPath、v3_throwAbortReason等未来特性开关与tsconfigPaths()。此外它还通过routes(defineRoutes)注册了一条自定义路由/product/category/:handle展示如何在约定路由之外追加映射并将assetsInlineLimit设为 0以便在启用严格 CSPContent-Security-Policy时资源不被内联为 base64。本地开发与生产构建package.json中的脚本是日常开发的直接入口命令作用npm run dev启动本地开发服务器底层为shopify hydrogen devnpm run build构建生产产物shopify hydrogen build --no-lockfile-checknpm run serve本地预览生产构建结果shopify hydrogen previewnpm run lint使用 ESLint 检查.js/.ts/.jsx/.tsx--no-error-on-unmatched-pattern避免无匹配时报错npm run typecheck运行tsc --noEmit做类型检查npm run codegen运行shopify hydrogen codegen重新生成 GraphQL 类型npm test以SERVER_NAMEhydrogen运行sdk/tests的 snippet 测试值得注意的是dev与build都直接由 Shopify CLI 驱动这意味着本地开发体验包括 Worker 模拟、Storefront 代理等与生产环境保持一致--no-lockfile-check则允许在依赖锁定文件与 package.json 不一致时仍继续构建。在 Remix 路由中渲染 Builder.io 内容这是本示例相对官方 Skeleton 的核心增量。Builder.io 的内容通过fetchOneEntry拉取、通过Content组件渲染整体封装在一个可复用的组件中见 app/components/app.tsxconst BUILDER_API_KEY ee9f13b4981e489a9a1209887695ef2b; const model page; export const builderLoader: LoaderFunction async ({params, request}) { const pathname /${params[*] || }; const content await fetchOneEntry({ model, apiKey: BUILDER_API_KEY, userAttributes: {urlPath: pathname}, }); return {content, model, searchParams: Object.fromEntries(url.searchParams)}; };要点拆解userAttributes.urlPath用于按当前访问路径匹配 Builder 后台配置的内容条目这是实现路径 → 可视化内容映射的关键isPreviewing(searchParams)判断当前请求是否来自 Builder 可视化编辑器带编辑态查询参数从而在无内容时也能渲染空白画布供编辑Content组件接收model、apiKey、content并透传 Hydrogen 提供的nonce保证在 CSP 环境下 SDK 动态渲染正常。这个 loader 通过两个路由复用_index.tsx首页与$.tsxcatch-all 通配路由后者让任意未命中具体路由的路径都回落到 Builder 页面实现整站内容由 Builder 托管的效果export const loader: LoaderFunction builderLoader; export default BuilderPage;场景化示例产品详情页与公告栏除了通用页面示例还演示了两种典型的电商场景。产品详情页app/routes/products.$handle.tsx使用模型product-editorialloader 中先从dummyjson.com拉取商品数据再按当前路径url.pathname获取 Builder 的编辑型内容两者一并返回页面则由ProductHeader、ProductInfo、Content与ProductFooter组合渲染Content负责承载由市场/运营人员在 Builder 后台编排的专题内容块从而实现商品数据来自 Shopify/外部 API、展示编排来自 Builder的分工。文件还额外演示了isPreviewing()的空态处理既无商品数据又无 Builder 内容时渲染 404。公告栏app/components/AnnouncementBarPage.tsx使用模型announcement-barloader 按/announcements/${params[*] || }的路径前缀拉取内容页面在有内容时渲染公告条、否则渲染占位文案The rest of your page goes here。对应的路由文件为 app/routes/announcements.$.tsx其命名中的$表示该路由会匹配announcements下的所有子路径。服务端入口三大客户端的一次性装配Hydrogen 应用以 Workerfetch处理器为入口server.ts在请求到达时按序完成四件事会话与缓存校验SESSION_SECRET环境变量缺失直接抛错并返回 500随后并行打开名为hydrogen的缓存实例与AppSession.init(request, [env.SESSION_SECRET])会话Storefront 客户端通过createStorefrontClient装配需要PUBLIC_STOREFRONT_API_TOKEN、PRIVATE_STOREFRONT_API_TOKEN、PUBLIC_STORE_DOMAIN、PUBLIC_STOREFRONT_ID等环境变量并以getStorefrontHeaders(request)透传请求头Customer Account 客户端通过createCustomerAccountClient装配依赖PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID与PUBLIC_CUSTOMER_ACCOUNT_API_URL购物车处理器通过createCartHandler组合storefront、customerAccount与cartGetIdDefault/cartSetIdDefault的会话存取策略并用CART_QUERY_FRAGMENT定义购物车查询片段。最终这些客户端连同env、waitUntil一起注入 Remix 的getLoadContext供各路由的 loader 消费。文件末尾的getLocaleFromRequest还演示了多语言策略从子域名ES、FR、DE、JP推断I18nLocale未命中时回退到{language: EN, country: US}。CSP 配置让 Builder 编辑器与 CDN 正常工作Builder.io 的 SDK 依赖远程 CDN 与可视化编辑器因此在 app/entry.server.tsx 中通过 Hydrogen 的createContentSecurityPolicy显式放行了相关来源这份配置是模板默认自带的关键安全适配connectSrc: [https://cdn.builder.io]允许 SDK 的 API 调用imgSrc: [https://cdn.builder.io, http://localhost:*, ...]允许加载 Builder CDN 图片及本地开发资源scriptSrc: [unsafe-eval, http://localhost:*]允许 SDK 动态求值绑定表达式frameAncestors: [https://builder.io, http://localhost:*]允许 Builder 可视化编辑器在 iframe 中嵌入应用。生成的 CSP 头通过responseHeaders.set(Content-Security-Policy, header)写入响应同时渲染使用renderToReadableStream并借助NonceProvider与nonce贯穿ScrollRestoration、Scripts保证脚本策略可精细化管控。文件还通过isbot对爬虫请求执行await body.allReady确保搜索引擎抓取到完整渲染的 HTML。接入 Customer Account API/account 区若要在应用中启用会员账户功能/account区官方要求先完成两步前置配置为本地开发配置一个公网域名完成对应的客户账户 API 应用配置。之后服务端入口中的createCustomerAccountClient即可正常联通账户相关的 GraphQL 查询与变更如CustomerDetailsQuery、CustomerOrdersQuery、CustomerOrderQuery、CustomerUpdateMutation、CustomerAddressMutations见 app/graphql/customer-account会在npm run codegen时自动生成类型。注意启用前必须确认PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID与PUBLIC_CUSTOMER_ACCOUNT_API_URL两个环境变量已正确设置。小结Hydrogen Skeleton 模板以最小化姿态覆盖了无头电商的完整链路Remix 路由与数据流、Storefront/Customer Account/Cart 三客户端、Oxygen Worker 部署形态以及基于 Shopify CLI 的 dev/build/preview/codegen 工作流。本仓库的示例在此基础上叠加 Builder.io给出了商品与账户数据归 Shopify、页面与专题内容编排归 Builder的清晰分工并通过 CSP 放行、nonce透传、catch-all 路由等细节保证了可视化开发与生产安全的兼容。无论是从 packages/sdks/snippets/hydrogen 直接研究源码还是用npm create shopify/hydrogenlatest从零起步本文覆盖的脚本、配置与调用链都能帮助你快速完成从脚手架到 Builder.io 可视化页面的落地。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 Shopify Hydrogen 无头电商中集成 Builder.io：Skeleton 模板实战指南
在 Shopify Hydrogen 无头电商中集成 Builder.ioSkeleton 模板实战指南【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builderHydrogen 是 Shopify 面向无头商务headless commerce推出的技术栈专门设计与 Shopify 的全栈 Web 框架 Remix 深度配合。本仓库中的 Hydrogen 示例位于 packages/sdks/snippets/hydrogen在官方 Skeleton 模板之上用最小化的组件、查询与工具链演示了如何把 Builder.io 的可视化开发能力接入 Hydrogen 应用。读完本文你将掌握 Hydrogen Skeleton 模板的初始化、本地开发与生产构建流程理解 Storefront / Customer Account / Cart 三套客户端在服务端入口中的装配方式并能在 Hydrogen 的 Remix 路由中落地 Builder.io 的fetchOneEntryContent渲染管线。模板定位为无头商务而生的最小化起点官方 Skeleton 模板的核心设计哲学是最小化只包含跑通一条完整链路所必需的组件、查询与工具而不是一个功能堆砌的巨型脚手架。其技术底座包含Remix全栈 Web 框架负责路由、加载器与数据流编排HydrogenShopify 官方无头商务 SDK提供 Storefront、Customer Account、Cart 等客户端OxygenShopify 的托管运行时让应用以 Worker 形态部署Vite构建与开发服务器Shopify CLI开发、构建、预览与代码生成的一站式命令行工具ESLint 与 Prettier代码质量与格式规范GraphQL generator由 Storefront 与 Customer Account API 的 GraphQL Schema 自动生成类型TypeScript 与 JavaScript 双风味同一套模板可选择 TS 或 JS 起步最小化的组件与路由集便于在此基础上快速扩展。在本仓库中这套模板还被注入了 Builder.io 的 React SDKbuilder.io/sdk-react从而把可视化页面搭建能力嵌入无头电商站点这也正是该示例在builder项目中的独特价值所在。环境要求与项目初始化官方模板要求Node.js 18.0.0 或更高版本。初始化一个新项目只需一条命令npm create shopify/hydrogenlatest如果你希望在现有 Builder.io 仓库中直接研究或复用这套配置本示例的完整源码位于 packages/sdks/snippets/hydrogen其package.json中声明的核心依赖包括builder.io/sdk-react工作区引用、shopify/hydrogen2024.4.x、shopify/remix-oxygen、remix-run/react、shopify/cli-hydrogen以及graphql所有依赖都锁定在 package.json 中可直接安装运行。目录结构与工程布局模板采用 Remix 约定式路由配合 Hydrogen 的服务端入口与 Builder.io 的按模型model拆分组件packages/sdks/snippets/hydrogen/ ├── app/ │ ├── components/ # Builder 模型对应的页面组件 │ ├── graphql/ # Customer Account API 的查询与变更 │ ├── lib/ # fragments、session、variants、root-data 等 │ ├── routes/ # Remix 路由含 Builder 相关路由 │ ├── styles/ # reset.css / app.css │ ├── entry.client.tsx # 浏览器端入口 │ ├── entry.server.tsx # 服务端渲染入口含 CSP │ └── root.tsx # 根布局与错误边界 ├── server.ts # Worker fetch 入口装配三大客户端 ├── vite.config.ts # Hydrogen Oxygen Remix tsconfigPaths ├── storefrontapi.generated.d.ts ├── customer-accountapi.generated.d.ts └── package.jsonvite.config.ts是理解构建链的关键它依次挂载了hydrogen()、oxygen()、remix()使用hydrogen.preset()预设并开启了v3_fetcherPersist、v3_relativeSplatPath、v3_throwAbortReason等未来特性开关与tsconfigPaths()。此外它还通过routes(defineRoutes)注册了一条自定义路由/product/category/:handle展示如何在约定路由之外追加映射并将assetsInlineLimit设为 0以便在启用严格 CSPContent-Security-Policy时资源不被内联为 base64。本地开发与生产构建package.json中的脚本是日常开发的直接入口命令作用npm run dev启动本地开发服务器底层为shopify hydrogen devnpm run build构建生产产物shopify hydrogen build --no-lockfile-checknpm run serve本地预览生产构建结果shopify hydrogen previewnpm run lint使用 ESLint 检查.js/.ts/.jsx/.tsx--no-error-on-unmatched-pattern避免无匹配时报错npm run typecheck运行tsc --noEmit做类型检查npm run codegen运行shopify hydrogen codegen重新生成 GraphQL 类型npm test以SERVER_NAMEhydrogen运行sdk/tests的 snippet 测试值得注意的是dev与build都直接由 Shopify CLI 驱动这意味着本地开发体验包括 Worker 模拟、Storefront 代理等与生产环境保持一致--no-lockfile-check则允许在依赖锁定文件与 package.json 不一致时仍继续构建。在 Remix 路由中渲染 Builder.io 内容这是本示例相对官方 Skeleton 的核心增量。Builder.io 的内容通过fetchOneEntry拉取、通过Content组件渲染整体封装在一个可复用的组件中见 app/components/app.tsxconst BUILDER_API_KEY ee9f13b4981e489a9a1209887695ef2b; const model page; export const builderLoader: LoaderFunction async ({params, request}) { const pathname /${params[*] || }; const content await fetchOneEntry({ model, apiKey: BUILDER_API_KEY, userAttributes: {urlPath: pathname}, }); return {content, model, searchParams: Object.fromEntries(url.searchParams)}; };要点拆解userAttributes.urlPath用于按当前访问路径匹配 Builder 后台配置的内容条目这是实现路径 → 可视化内容映射的关键isPreviewing(searchParams)判断当前请求是否来自 Builder 可视化编辑器带编辑态查询参数从而在无内容时也能渲染空白画布供编辑Content组件接收model、apiKey、content并透传 Hydrogen 提供的nonce保证在 CSP 环境下 SDK 动态渲染正常。这个 loader 通过两个路由复用_index.tsx首页与$.tsxcatch-all 通配路由后者让任意未命中具体路由的路径都回落到 Builder 页面实现整站内容由 Builder 托管的效果export const loader: LoaderFunction builderLoader; export default BuilderPage;场景化示例产品详情页与公告栏除了通用页面示例还演示了两种典型的电商场景。产品详情页app/routes/products.$handle.tsx使用模型product-editorialloader 中先从dummyjson.com拉取商品数据再按当前路径url.pathname获取 Builder 的编辑型内容两者一并返回页面则由ProductHeader、ProductInfo、Content与ProductFooter组合渲染Content负责承载由市场/运营人员在 Builder 后台编排的专题内容块从而实现商品数据来自 Shopify/外部 API、展示编排来自 Builder的分工。文件还额外演示了isPreviewing()的空态处理既无商品数据又无 Builder 内容时渲染 404。公告栏app/components/AnnouncementBarPage.tsx使用模型announcement-barloader 按/announcements/${params[*] || }的路径前缀拉取内容页面在有内容时渲染公告条、否则渲染占位文案The rest of your page goes here。对应的路由文件为 app/routes/announcements.$.tsx其命名中的$表示该路由会匹配announcements下的所有子路径。服务端入口三大客户端的一次性装配Hydrogen 应用以 Workerfetch处理器为入口server.ts在请求到达时按序完成四件事会话与缓存校验SESSION_SECRET环境变量缺失直接抛错并返回 500随后并行打开名为hydrogen的缓存实例与AppSession.init(request, [env.SESSION_SECRET])会话Storefront 客户端通过createStorefrontClient装配需要PUBLIC_STOREFRONT_API_TOKEN、PRIVATE_STOREFRONT_API_TOKEN、PUBLIC_STORE_DOMAIN、PUBLIC_STOREFRONT_ID等环境变量并以getStorefrontHeaders(request)透传请求头Customer Account 客户端通过createCustomerAccountClient装配依赖PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID与PUBLIC_CUSTOMER_ACCOUNT_API_URL购物车处理器通过createCartHandler组合storefront、customerAccount与cartGetIdDefault/cartSetIdDefault的会话存取策略并用CART_QUERY_FRAGMENT定义购物车查询片段。最终这些客户端连同env、waitUntil一起注入 Remix 的getLoadContext供各路由的 loader 消费。文件末尾的getLocaleFromRequest还演示了多语言策略从子域名ES、FR、DE、JP推断I18nLocale未命中时回退到{language: EN, country: US}。CSP 配置让 Builder 编辑器与 CDN 正常工作Builder.io 的 SDK 依赖远程 CDN 与可视化编辑器因此在 app/entry.server.tsx 中通过 Hydrogen 的createContentSecurityPolicy显式放行了相关来源这份配置是模板默认自带的关键安全适配connectSrc: [https://cdn.builder.io]允许 SDK 的 API 调用imgSrc: [https://cdn.builder.io, http://localhost:*, ...]允许加载 Builder CDN 图片及本地开发资源scriptSrc: [unsafe-eval, http://localhost:*]允许 SDK 动态求值绑定表达式frameAncestors: [https://builder.io, http://localhost:*]允许 Builder 可视化编辑器在 iframe 中嵌入应用。生成的 CSP 头通过responseHeaders.set(Content-Security-Policy, header)写入响应同时渲染使用renderToReadableStream并借助NonceProvider与nonce贯穿ScrollRestoration、Scripts保证脚本策略可精细化管控。文件还通过isbot对爬虫请求执行await body.allReady确保搜索引擎抓取到完整渲染的 HTML。接入 Customer Account API/account 区若要在应用中启用会员账户功能/account区官方要求先完成两步前置配置为本地开发配置一个公网域名完成对应的客户账户 API 应用配置。之后服务端入口中的createCustomerAccountClient即可正常联通账户相关的 GraphQL 查询与变更如CustomerDetailsQuery、CustomerOrdersQuery、CustomerOrderQuery、CustomerUpdateMutation、CustomerAddressMutations见 app/graphql/customer-account会在npm run codegen时自动生成类型。注意启用前必须确认PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID与PUBLIC_CUSTOMER_ACCOUNT_API_URL两个环境变量已正确设置。小结Hydrogen Skeleton 模板以最小化姿态覆盖了无头电商的完整链路Remix 路由与数据流、Storefront/Customer Account/Cart 三客户端、Oxygen Worker 部署形态以及基于 Shopify CLI 的 dev/build/preview/codegen 工作流。本仓库的示例在此基础上叠加 Builder.io给出了商品与账户数据归 Shopify、页面与专题内容编排归 Builder的清晰分工并通过 CSP 放行、nonce透传、catch-all 路由等细节保证了可视化开发与生产安全的兼容。无论是从 packages/sdks/snippets/hydrogen 直接研究源码还是用npm create shopify/hydrogenlatest从零起步本文覆盖的脚本、配置与调用链都能帮助你快速完成从脚手架到 Builder.io 可视化页面的落地。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考