Builder.io 官方示例贡献指南编写高质量框架集成示例的规范与最佳实践【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builderBuilder.io 是一个可视化开发平台支持 React、Vue、Svelte、Qwik、Angular、Next.js、Remix 等多种框架与元框架。为了让开发者快速理解Builder.io 如何与一个网站集成本仓库维护了examples/目录下 40 余个框架示例如 react-js、next-js-simple、svelte、qwik 等。本文以官方规范文档 examples/CONTRIBUTING.md 为骨架系统梳理为这些示例贡献代码时必须遵守的编写准则并结合仓库内真实示例源码与packages/sdks的底层实现说明每一条规范背后的原因与落地方式。读完本文你将掌握一套可复用的示例代码审查清单能够独立为任何框架的 Builder 集成示例写出简洁、易懂、可运行且遵循最佳实践的代码。示例的定位为发现与学习服务examples/目录不是生产代码它的存在目的只有一个展示 Builder.io 如何与一个站点集成并让开发者一眼就能看懂。因此贡献示例时的第一原则是保持简单Keep it simple任何妨碍读者快速定位核心集成点的内容都应该被删除或简化。从 examples 目录可以看到每个框架的示例都刻意保持最小结构例如 examples/react-js 仅包含src/main.jsx与src/index.css两个源文件examples/next-js-simple 只有pages/[[...page]].tsx、pages/_app.tsx、config/builder.ts与一个自定义Link组件。这种麻雀虽小、五脏俱全的结构正是文档所倡导的目标形态。核心准则一保持简单Keep it simple1. 使用尽可能少的样板代码如果你是从某个官方脚手架生成项目后再接入 Builder请务必删除一切与演示无关的内容示例 API 路由、示例 CSS、hello world 代码、未注册给 Builder 使用的示例组件统统清理掉。开发者真正需要的是核心集成点而不是迷失在无关样板中。文档给出了正反两个目录结构示例# ✅ 好的示例结构只有核心集成点 src/ components/ example-component.jsx # example component pages/ [...page].jsx # example page# ❌ 应避免的结构杂物太多难以找到重点 src/ components/ my-component.jsx index.js pages/ index.jsx styles/ index.css api/ example-api.js utils/ my-utils.js这一原则在仓库中有直观印证例如 examples/react-multipage-funnel 仅用少量源码配合builder/下的 8 个 JSON 内容模型就完整演示了多页漏斗场景examples/react-design-system 则以src/中的 37 个组件加builder/下的 20 个 JSON 文件聚焦于设计系统这一个主题而不是堆砌无关功能。2. 使用尽可能少的抽象避免一切自定义封装尽量直接使用 Builder SDK 提供的 API。理由很直接示例的读者是想学习 Builder 的 SDK/API本身而不是学习你的私有封装。文档的正反对比如下// ✅ 好的做法直接调用 SDK import { getContent } from builder.io/sdk-react getContent(...)// ❌ 应避免在 SDK 之上再包一层无意义抽象 import { getBuilderContent } from ./get-builder-content // Unnecessary abstraction away from the APIs people are trying to learn getBuilderContent(...)这个直接调用 SDK的约定在真实示例中得到了严格贯彻。以 examples/next-js-simple/pages/[[...page]].tsx 为例页面数据获取直接使用builder.get(page, ...)与builder.getAll(page, ...)没有引入任何中间封装examples/react-js/src/main.jsx 同样直接使用builder.getAll(page, {...})拉取页面列表。SDK 的底层函数可以在 packages/sdks/src/functions/get-content/index.ts 中看到fetchOneEntry返回匹配的首条内容与fetchEntries返回分页数组正是getContent/getAll系列 API 的服务端实现读者想深入时可以顺着这条链路继续阅读。3. 使用注释Use comments注释的作用是在代码上下文里向对 Builder 完全陌生的新人解释这里正在发生什么。文档推荐在关键调用点逐行说明含义例如export async function getStaticProps() { // Get the page from Builder.ios API const page await getContent({ // Provide your model name model: page, // Provide the current URL url: / // You can add other options here: // 完整选项见仓库内 GetContentOptions 类型定义 }) if (!page) { // If no page exists, show a 404 return { notFound: true } } return { props: { page } } }// ❌ 应避免没有任何解释的裸调用 export async function getStaticProps() { const page await getContent({ model: page, url: / }) if (!page) { return { notFound: true } } return { props: { page } } }其中getContent的可选参数全集model、url、userAttributes、query、fields、omit、limit、offset、sort、locale、enrich、apiVersion、cacheSeconds、includeUnpublished等可以在 SDK 的类型定义 packages/sdks/src/functions/get-content/types.ts 中查阅示例中凡是出现这类关键 API都应当配上指向该定义的注释方便读者展开学习。实际示例同样践行了注释解释上下文的做法examples/react-js/src/main.jsx 中逐段注释了get the page content from Builderif no page is found, return a 404 pageRender the Builder page等关键语义让不熟悉 Builder 的读者也能顺着注释读完整个渲染流程。4. 使用 JavaScript 而非 TypeScript这条准则可能会让很多习惯 TypeScript 的开发者意外示例请使用 JavaScript。文档给出的理由是并非所有开发者都熟悉 TypeScript但使用 Builder 的前提是懂 JavaScript去掉类型语法能让示例更小、更简单避免引入可能不被理解的额外语法。// ✅ 好的做法普通 JavaScript 函数 export const getStaticProps async (context) { // ... }// ❌ 应避免引入类型标注 import type { GetStaticProps } from next export const getStaticProps: GetStaticProps async (context) { // ... }这一建议也反映在示例目录的构成上examples/react-js、examples/plain-js、examples/node-express 等示例均以.js/.jsx为主同时仓库也保留了一批 TS 示例如 examples/next-js-simple、examples/qwik用于演示框架自身的 TS 生态贡献新示例时可根据目标框架惯例权衡但原则上优先保证对纯 JS 开发者零门槛。5. 有效使用 README.mdUse the README.md effectively每个示例必须有一个高质量的 README开头用一两句话说明这个示例是什么、应该先看哪些文件然后说明如何开始运行。# ✅ 好的 README 开头 # Builder.io example with SvelteKit This is an example of using Builder with SvelteKit. See pages/index.svelte to see the example integration point in detail ## Get Started ...# ❌ 应避免只有一句话的 README # SvelteKit Builder and Svelteexamples/next-js-simple/README.md 是这一规范的最佳范本开头即点明This example walks you through using Builder.io with a minimal Next.js application随后依次给出前置条件Builder 账号、npm、概述clone 仓库 → 创建 Builder space → 连接二者、逐步配置设置模型 Preview URL、获取 Public API Key、写入BUILDER_PUBLIC_KEY环境变量、本地运行npm install→npm run dev→ 访问http://localhost:3000、实验与部署指引。贡献者可以直接照此结构组织自己的示例 README。核心准则二引导读者走向最佳实践Use best practices规范的第二大部分要求示例本身必须是最佳实践的活教材把读者引导到成功的坑位pit of success上。1. 优先 SSR/SSG而非纯客户端渲染只要框架支持就应该用服务端渲染/静态生成的方式获取内容而不是全部在客户端完成。文档的正反示例对比鲜明// ✅ 好的做法内容在服务端取好通过 props 传入 export default function MyPage({ builderJson }) { return RenderContent content{builderJson} / }// ❌ 应避免客户端 useEffect 里才拉取内容 export default function MyPage({ builderJson }) { const [builderJson, setBuilderJson] useEffect(null) useEffect(() { getContent(...).then(setBuilderJson }, []) return RenderContent content{builderJson} / }注文档此处反例中的useEffect(null)为示意性笔误实际意图是强调不要在客户端副作用里获取内容。这一原则在 examples/next-js-simple/pages/[[...page]].tsx 中得到完整落地getStaticProps中同步获取 Builder 内容配合revalidate: 5启用 ISR增量静态再生成getStaticPaths中调用builder.getAll(page, { options: { noTargeting: true }, omit: data.blocks })预生成全部页面路径omit: data.blocks用于在列路径阶段省去巨大的 blocks 数据这是文档未明说但示例中值得学习的性能细节。只有fallback兜底渲染和预览态useIsPreviewing才走运行时逻辑。再往底层看packages/sdks的 SDK 本身就是为 SSR 设计的在 packages/sdks/src/functions/get-content/index.ts 的_processContentResult中A/B 测试与预览内容的处理逻辑会根据运行环境分派——浏览器或 React Native 环境下走handleABTesting动态分流SSR 场景则依赖服务端多渲染变体方案这解释了为什么文档要求尽量 SSR/SSG 兼容因为内容获取管线在不同环境下的行为是经过精心设计的。2. 始终包含 header 和 footerBuilder 不是空白画布式页面构建器它主张融入并保持与既有站点一致。因此每个示例页面都要带上占位的 header 和 footer示意Builder 内容应该嵌入到真实站点结构中// ✅ 好的做法Builder 渲染区被站点外壳包裹 export default function MyPage({ builderJson }) { return ( MyHeader / RenderContent content{builderJson} / MyFooter / / ) }// ❌ 应避免裸渲染 Builder 内容没有站点外壳 export default function MyPage({ builderJson }) { return RenderContent content{builderJson} / }examples/react-js/src/main.jsx 是这一模式的直接体现App组件在最外层渲染了带 logo 的header与导航链接中间才是路由与BuilderComponent modelpage content{content} /的渲染区域。这种外壳 Builder 渲染区的结构就是 Builder 官方推荐的真实站点集成形态。3. 使用描述性变量名Use descriptive variable namesBuilder 引入了一整套新的抽象概念model、content、blocks、targeting……因此变量名越具象越好尤其不要用builder这种毫无信息量的名字。// ✅ 好的做法名字说明内容的来源与含义 const builderPageJson await getContent(...)// ❌ 应避免在 builder 示例里把内容命名为 builder // 在 builder 示例的语境下它没有任何有价值的信息还可能造成额外混淆 const builder await getContent(...)这一点同样在真实示例中得到遵守examples/next-js-simple/pages/[[...page]].tsx 中将取回的内容命名为page配合model: page语义清晰examples/react-js/src/main.jsx 命名为content与后续content{content}的渲染调用一一对应。从源码看getContent的完整能力示例注释背后的真相文档示例中反复出现的getContent绝非魔法。在 packages/sdks/src/functions/get-content/generate-content-url.ts 中可以读到它如何把选项翻译为对 Builder CDN 的请求默认值limit默认 30当limit ! 1时自动设置noTraversetrue以提升性能源码注释明确说明这是出于性能考虑必填校验缺少apiKey会直接抛出Missing API key非法apiVersion仅接受v3会抛出异常可选参数locale、enrich/enrichOptions富化关联数据、fields只取指定字段、omit默认省略meta.componentsUsed、offset、sort、includeUnpublished、cacheSeconds/staleCacheSeconds、apiHost默认https://cdn.builder.io等都会被映射为 CDN URL 的查询参数。理解了这一层示例注释中那句You can add other options here就有了扎实的落点读者可以根据 GetContentOptions 类型定义 与上述 URL 生成逻辑把fields、locale、enrich等选项自由组合进自己的示例并准确预期它们对请求与返回结果的影响。贡献前的自查清单综合 examples/CONTRIBUTING.md 全文向examples/提交新示例前可以按如下清单逐项核对最小化目录里是否只剩核心集成点 必要支撑无关的脚手架代码、示例 API、示例样式是否已删除零抽象是否直接使用builder.io/sdk-*或builder.io/react的公开 API而非私有封装有注释每个 Builder 关键调用点是否有上下文内注释解释 model、url、options 的含义低门槛代码是否优先使用 JavaScript而非 TypeScript避免对纯 JS 开发者造成额外语法负担好 README是否在开头说明了这个示例是什么 先看哪个文件并给出了完整的 Get Started 步骤参考 examples/next-js-simple/README.md最佳实践内容获取是否优先走 SSR/SSG参考 examples/next-js-simple/pages/[[...page]].tsx页面是否包含 header/footer 站点外壳变量名是否描述了内容的含义避免裸用builder结语高质量的示例是 Builder 生态的门面它让一个完全陌生的开发者能在几分钟内从看到代码走到跑通自己的站点。examples/CONTRIBUTING.md虽然只有短短几百行却浓缩了官方对示例的全部期望——简单、直接、有注释、低门槛、可运行、遵循 SSR 最佳实践。对照本文整理的自查清单你既能写出符合官方规范的示例也能借此更深入地理解 Builder SDK 在 packages/sdks/src/functions/get-content 下的真实工作方式。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考