Builder.io 可视化开发指南在 React、Vue、Svelte、Qwik 等任意技术栈上实现设计转代码与一键发布【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder本篇指南围绕 Builder.io 的核心定位Visual Development On Any Stack展开结合本仓库builder.io/root内真实的 SDK、示例、启动器与插件源码系统讲解其工作原理、SDK 双代际架构、内容获取与渲染的核心 API、自定义组件注册、Monorepo 构建流程以及运行环境注意事项。读完你将掌握如何在现有 React/Vue/Svelte/Qwik 等应用中接入 Builder用 Figma 设计或拖拽编辑器可视化生成与编辑页面并通过官方 SDK 导出代码或一键发布更新。Builder.io 平台如何工作Builder.io 的核心思路不是让你把应用搬到某个平台上而是连接到你已经存在的站点或应用让非技术人员或你自己可以基于现有组件进行可视化编辑与代码生成。官方根 README.md 将其概括为三步连接现有代码库Builder 通过 SDK 感知你应用中已有的组件与数据可视化编辑可以使用 Figma 设计稿也可以使用内置的拖拽式编辑器直接操作这些现有组件导出或发布将编辑结果导出为代码或通过各框架的 SDKs 将更新直接发布到线上。其中通过 SDK 导出代码或发布更新是技术落地的关键——仓库里全部的内容获取、渲染、注册自定义组件的代码都围绕这一环节展开下文会逐一深入。仓库全景SDK、示例、启动器与插件根 README 明确指出本仓库承载了四类资产这也是理解整个项目的最佳入口目录内容说明packages各类 SDK 与核心包包括新代际 SDK、Gen1 React SDK、Core SDK、CLI、插件工具等examples使用示例覆盖 Angular、Next.js、React、Svelte、Vue、Qwik 等框架的接入样例starters启动器项目开箱即用的模板如 starters/create-builderplugins插件生态如 Algolia、Cloudinary、Shopify、Contentful 等第三方集成的官方插件其中 packages/sdks/README.md 明确列出了当前支持的全部 SDKReact-Native、Vue 3、Svelte、SolidJS、Angular、Qwik、React以及用于 React Server Components 注册支持的 NextJS实验性。也就是说无论你的技术栈是组件化框架还是原生渲染框架都能找到对应的接入入口。SDK 双代际架构Gen1 与 Gen2从源码结构看仓库中存在两代 SDK它们的设计哲学差异明显Gen1builder.io/react与builder.io/sdkcoreGen1 以 packages/core 为核心。它本质上是 BuilderContent API 的轻量封装见 packages/core/README.md提供builder.init()、builder.get()、builder.getAll()、builder.setUserAttributes()等命令式 API。在此基础上packages/react/README.md 提供了BuilderComponent /、BuilderContent /等声明式组件以及全局单例Builder用于注册自定义组件。Gen2由 Mitosis 生成的多框架 SDKGen2 SDK 是用 Mitosis 编写一份源码、自动生成多种框架代码的新代际方案详见 packages/sdks/README.md 与 packages/sdks/docs/ARCHITECTURE.md统一的 Mitosis 源码位于 packages/sdks/src其中src/blocks存放 Text、Image、Columns 等 Builder 内置块src/components存放渲染 SDK 所需的组件生成的各框架代码位于 packages/sdks/output对应 angular、nextjs、qwik、react、react-native、solid、svelte、vue 八个目录以 React 为例Gen2 产物是builder.io/sdk-react官方称其拥有零客户端依赖、更小的打包体积约 25kb并额外提供builder.io/sdk-react/edge用于 Serverless 环境见 packages/sdks/output/react/README.md。这种一次编写、多端生成的架构正是On Any Stack这一平台定位得以成立的工程基础。实战获取内容与渲染页面Builder 的结构与传统 Headless CMS 类似内容类型称为model默认每个 space 都有一个pagemodel通过查询与定向targeting获取内容后渲染。Gen1 Reactbuilder.get()BuilderComponent /packages/react/README.md 给出了最简接入范式import { builder } from builder.io/react const API_KEY ... // 你的 Builder public API key const MODEL_NAME page const content await builder .get(MODEL_NAME, { // 可选自定义查询如按自定义字段过滤 query: { data.customField.$gt: 100, }, // 可选自定义定向大多数内容至少按 URL 路径定向 userAttributes: { urlPath: /, }, }) .promise() // 将取到的内容 JSON 交给 BuilderComponent 渲染 BuilderComponent model{MODEL_NAME} content{content} /在 Next.js 中可在getStaticProps里预取内容并渲染为首页同样来自 packages/react/README.mdexport const getStaticProps async () { return { props: { builderContent: await builder .get(page, { userAttributes: { urlPath: / }, // 获取定向到首页 / 的内容 }) .promise(), }, }; }; export default function MyHomePage({ builderContent }) { return ( YourHeader / BuilderComponent modelpage content{builderContent} / YourFooter / / ); }builder.get的全部可选参数如query、userAttributes、limit等可查看 core 包的接口文档 packages/core/docs/interfaces/GetContentOptions.md。Gen2 ReactfetchOneEntry()Content /新一代 React SDK 改用函数式 API使用方式节选自 packages/sdks/output/react/README.mdimport { Content, fetchOneEntry, isPreviewing } from builder.io/sdk-react; import { useEffect, useState } from react; const BUILDER_PUBLIC_API_KEY YOUR API KEY; function App() { const [content, setContent] useState(undefined); useEffect(() { fetchOneEntry({ model: page, apiKey: BUILDER_PUBLIC_API_KEY, userAttributes: { urlPath: window.location.pathname || /, }, }).then((content) setContent(content)); }, []); const shouldRenderBuilderContent content || isPreviewing(); return shouldRenderBuilderContent ? ( Content content{content} modelpage apiKey{BUILDER_PUBLIC_API_KEY} / ) : ( divContent Not Found/div ); }isPreviewing()用于判断当前是否处于 Builder 可视化编辑器预览态保证编辑器中能实时看到渲染结果——这正是可视化编辑能力在代码侧的落点。注册自定义组件让编辑器认识你的组件用现有组件做可视化编辑的前提是向 Builder 注册组件。packages/react/README.md 中的核心 API 是全局单例Builder.registerComponent()注册后组件即可出现在拖拽编辑器的组件面板中并通过inputs声明可编辑的属性import * as React from react; import SyntaxHighlighter from react-syntax-highlighter; import { Builder } from builder.io/react; class CodeBlockComponent extends React.Component { render() { return SyntaxHighlighter language{this.props.language}{this.props.code}/SyntaxHighlighter; } } Builder.registerComponent(CodeBlockComponent, { name: Code Block, inputs: [ { name: code, type: string, defaultValue: const incr num num 1, }, { name: language, type: string, defaultValue: javascript, }, ], });inputs中的每个字段都会成为编辑器表单中的可编辑项值将作为同名 props 传入组件。你可以选择让自定义组件与内置组件并存也可以通过 components-only 模式只允许使用自定义组件。用data与context向渲染树传值BuilderComponent /支持向下传递数据与函数供 Builder 中的 actions 与 bindings 以state.*使用BuilderComponent modelpage data{{ products: productsList, foo: bar }} content{builderJson} /对于需要穿透整个渲染树例如跨 Symbol且不参与响应式观察的复杂对象、函数或库使用context类似 React Context在 actions 与 bindings 中通过context.*访问例如context.lodash或context.addToCart()见 packages/react/README.md。Monorepo 与构建流程一份源码生成全部 SDK仓库是一个以 yarn v3 workspaces 与 Nx 与 packages/sdks/docs/ARCHITECTURE.md。monorepo 包含packages/sdksGen2 SDK 与集成测试、packages/reactGen1 React SDK、packages/coreGen1 核心、packages/react-tests与packages/sdks-tests集成测试。Gen2 SDK 的构建流程按依赖顺序推进先构建 core 与 Gen1 React SDKGen2 依赖的 Mitosis 又依赖 Gen1 React SDK运行 Mitosis 构建在packages/sdks/output下生成各框架源码各 SDK 用自身工具链Vite/Rollup 或框架专用工具构建最后构建并运行位于packages/sdks-tests的集成测试。值得注意的工程细节均出自 packages/sdks/docs/ARCHITECTURE.md每个 SDK 生成 3 个 bundle由于部分代码与运行环境强相关尤其是执行任意 JS 的evaluator每个 SDK 分别构建 browser、NodeJS 与 edge 三个运行时版本产物通常位于各 output 目录的lib/edge、lib/node、lib/browserMitosis 配置与插件packages/sdks/mitosis.config.js定义了 Mitosis 构建的全部配置大量插件按输出目标改写生成的代码packages/sdks/overrides则用于个别 SDK 的整文件覆盖一种最后手段需要与源文件保持同名导出与参数生成逻辑的组件分层ContentVariants处理 A/B 测试并对每个变体调用ContentContent调用BlocksBlocks再逐块调用Block而Block的渲染又被拆分为RepeatedBlock、BlockWrapper、ComponentRef等子组件以规避 Svelte 与 React Server Components 的多重限制。运行环境注意事项Node v20 Apple Siliconpackages/sdks/README.md 与 packages/react/README.md 都记录了一个重要的兼容性问题SDK 在 Node 服务端依赖isolated-vm安全执行代码而该库在Node v20 M1 MacApple Silicon上存在兼容性问题。解决方法是给运行服务的命令加上环境变量NODE_OPTIONS--no-node-snapshot yarn dev若未提供该标志SDK 在 Apple Silicon Node v20 环境下会跳过使用isolated-vm。更多资源示例与官方站点examples/next-js-builder-site使用 Next.js 静态站点生成能力构建的 Builder 官方站点博客、文档与营销页是用 Builder 造 Builder的最佳参考examples/react-v2、examples/nextjs-app-dir-v2、examples/nextjs-pages-dir-v2Gen2 SDK 的官方示例分别对应 React Vite、Next.js App Router 与 Pages Router见 packages/sdks/output/react/README.mdexamples/next-js-cms-blog以 Builder 为 CMS 数据源的博客示例可直观体会页面/区块/CMS 数据三种集成形态pluginsAlgolia、Cloudinary、Contentful、Shopify 等官方插件展示如何扩展编辑器能力starters/create-builder一键生成新项目的启动器。如需快速体验可按照各 SDK 的安装命令如npm install builder.io/sdk-react与示例代码接入你自己的应用仓库本身是只读的所有接入与运行均在你的项目中进行。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Builder.io 可视化开发指南：在 React、Vue、Svelte、Qwik 等任意技术栈上实现设计转代码与一键发布
Builder.io 可视化开发指南在 React、Vue、Svelte、Qwik 等任意技术栈上实现设计转代码与一键发布【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder本篇指南围绕 Builder.io 的核心定位Visual Development On Any Stack展开结合本仓库builder.io/root内真实的 SDK、示例、启动器与插件源码系统讲解其工作原理、SDK 双代际架构、内容获取与渲染的核心 API、自定义组件注册、Monorepo 构建流程以及运行环境注意事项。读完你将掌握如何在现有 React/Vue/Svelte/Qwik 等应用中接入 Builder用 Figma 设计或拖拽编辑器可视化生成与编辑页面并通过官方 SDK 导出代码或一键发布更新。Builder.io 平台如何工作Builder.io 的核心思路不是让你把应用搬到某个平台上而是连接到你已经存在的站点或应用让非技术人员或你自己可以基于现有组件进行可视化编辑与代码生成。官方根 README.md 将其概括为三步连接现有代码库Builder 通过 SDK 感知你应用中已有的组件与数据可视化编辑可以使用 Figma 设计稿也可以使用内置的拖拽式编辑器直接操作这些现有组件导出或发布将编辑结果导出为代码或通过各框架的 SDKs 将更新直接发布到线上。其中通过 SDK 导出代码或发布更新是技术落地的关键——仓库里全部的内容获取、渲染、注册自定义组件的代码都围绕这一环节展开下文会逐一深入。仓库全景SDK、示例、启动器与插件根 README 明确指出本仓库承载了四类资产这也是理解整个项目的最佳入口目录内容说明packages各类 SDK 与核心包包括新代际 SDK、Gen1 React SDK、Core SDK、CLI、插件工具等examples使用示例覆盖 Angular、Next.js、React、Svelte、Vue、Qwik 等框架的接入样例starters启动器项目开箱即用的模板如 starters/create-builderplugins插件生态如 Algolia、Cloudinary、Shopify、Contentful 等第三方集成的官方插件其中 packages/sdks/README.md 明确列出了当前支持的全部 SDKReact-Native、Vue 3、Svelte、SolidJS、Angular、Qwik、React以及用于 React Server Components 注册支持的 NextJS实验性。也就是说无论你的技术栈是组件化框架还是原生渲染框架都能找到对应的接入入口。SDK 双代际架构Gen1 与 Gen2从源码结构看仓库中存在两代 SDK它们的设计哲学差异明显Gen1builder.io/react与builder.io/sdkcoreGen1 以 packages/core 为核心。它本质上是 BuilderContent API 的轻量封装见 packages/core/README.md提供builder.init()、builder.get()、builder.getAll()、builder.setUserAttributes()等命令式 API。在此基础上packages/react/README.md 提供了BuilderComponent /、BuilderContent /等声明式组件以及全局单例Builder用于注册自定义组件。Gen2由 Mitosis 生成的多框架 SDKGen2 SDK 是用 Mitosis 编写一份源码、自动生成多种框架代码的新代际方案详见 packages/sdks/README.md 与 packages/sdks/docs/ARCHITECTURE.md统一的 Mitosis 源码位于 packages/sdks/src其中src/blocks存放 Text、Image、Columns 等 Builder 内置块src/components存放渲染 SDK 所需的组件生成的各框架代码位于 packages/sdks/output对应 angular、nextjs、qwik、react、react-native、solid、svelte、vue 八个目录以 React 为例Gen2 产物是builder.io/sdk-react官方称其拥有零客户端依赖、更小的打包体积约 25kb并额外提供builder.io/sdk-react/edge用于 Serverless 环境见 packages/sdks/output/react/README.md。这种一次编写、多端生成的架构正是On Any Stack这一平台定位得以成立的工程基础。实战获取内容与渲染页面Builder 的结构与传统 Headless CMS 类似内容类型称为model默认每个 space 都有一个pagemodel通过查询与定向targeting获取内容后渲染。Gen1 Reactbuilder.get()BuilderComponent /packages/react/README.md 给出了最简接入范式import { builder } from builder.io/react const API_KEY ... // 你的 Builder public API key const MODEL_NAME page const content await builder .get(MODEL_NAME, { // 可选自定义查询如按自定义字段过滤 query: { data.customField.$gt: 100, }, // 可选自定义定向大多数内容至少按 URL 路径定向 userAttributes: { urlPath: /, }, }) .promise() // 将取到的内容 JSON 交给 BuilderComponent 渲染 BuilderComponent model{MODEL_NAME} content{content} /在 Next.js 中可在getStaticProps里预取内容并渲染为首页同样来自 packages/react/README.mdexport const getStaticProps async () { return { props: { builderContent: await builder .get(page, { userAttributes: { urlPath: / }, // 获取定向到首页 / 的内容 }) .promise(), }, }; }; export default function MyHomePage({ builderContent }) { return ( YourHeader / BuilderComponent modelpage content{builderContent} / YourFooter / / ); }builder.get的全部可选参数如query、userAttributes、limit等可查看 core 包的接口文档 packages/core/docs/interfaces/GetContentOptions.md。Gen2 ReactfetchOneEntry()Content /新一代 React SDK 改用函数式 API使用方式节选自 packages/sdks/output/react/README.mdimport { Content, fetchOneEntry, isPreviewing } from builder.io/sdk-react; import { useEffect, useState } from react; const BUILDER_PUBLIC_API_KEY YOUR API KEY; function App() { const [content, setContent] useState(undefined); useEffect(() { fetchOneEntry({ model: page, apiKey: BUILDER_PUBLIC_API_KEY, userAttributes: { urlPath: window.location.pathname || /, }, }).then((content) setContent(content)); }, []); const shouldRenderBuilderContent content || isPreviewing(); return shouldRenderBuilderContent ? ( Content content{content} modelpage apiKey{BUILDER_PUBLIC_API_KEY} / ) : ( divContent Not Found/div ); }isPreviewing()用于判断当前是否处于 Builder 可视化编辑器预览态保证编辑器中能实时看到渲染结果——这正是可视化编辑能力在代码侧的落点。注册自定义组件让编辑器认识你的组件用现有组件做可视化编辑的前提是向 Builder 注册组件。packages/react/README.md 中的核心 API 是全局单例Builder.registerComponent()注册后组件即可出现在拖拽编辑器的组件面板中并通过inputs声明可编辑的属性import * as React from react; import SyntaxHighlighter from react-syntax-highlighter; import { Builder } from builder.io/react; class CodeBlockComponent extends React.Component { render() { return SyntaxHighlighter language{this.props.language}{this.props.code}/SyntaxHighlighter; } } Builder.registerComponent(CodeBlockComponent, { name: Code Block, inputs: [ { name: code, type: string, defaultValue: const incr num num 1, }, { name: language, type: string, defaultValue: javascript, }, ], });inputs中的每个字段都会成为编辑器表单中的可编辑项值将作为同名 props 传入组件。你可以选择让自定义组件与内置组件并存也可以通过 components-only 模式只允许使用自定义组件。用data与context向渲染树传值BuilderComponent /支持向下传递数据与函数供 Builder 中的 actions 与 bindings 以state.*使用BuilderComponent modelpage data{{ products: productsList, foo: bar }} content{builderJson} /对于需要穿透整个渲染树例如跨 Symbol且不参与响应式观察的复杂对象、函数或库使用context类似 React Context在 actions 与 bindings 中通过context.*访问例如context.lodash或context.addToCart()见 packages/react/README.md。Monorepo 与构建流程一份源码生成全部 SDK仓库是一个以 yarn v3 workspaces 与 Nx 与 packages/sdks/docs/ARCHITECTURE.md。monorepo 包含packages/sdksGen2 SDK 与集成测试、packages/reactGen1 React SDK、packages/coreGen1 核心、packages/react-tests与packages/sdks-tests集成测试。Gen2 SDK 的构建流程按依赖顺序推进先构建 core 与 Gen1 React SDKGen2 依赖的 Mitosis 又依赖 Gen1 React SDK运行 Mitosis 构建在packages/sdks/output下生成各框架源码各 SDK 用自身工具链Vite/Rollup 或框架专用工具构建最后构建并运行位于packages/sdks-tests的集成测试。值得注意的工程细节均出自 packages/sdks/docs/ARCHITECTURE.md每个 SDK 生成 3 个 bundle由于部分代码与运行环境强相关尤其是执行任意 JS 的evaluator每个 SDK 分别构建 browser、NodeJS 与 edge 三个运行时版本产物通常位于各 output 目录的lib/edge、lib/node、lib/browserMitosis 配置与插件packages/sdks/mitosis.config.js定义了 Mitosis 构建的全部配置大量插件按输出目标改写生成的代码packages/sdks/overrides则用于个别 SDK 的整文件覆盖一种最后手段需要与源文件保持同名导出与参数生成逻辑的组件分层ContentVariants处理 A/B 测试并对每个变体调用ContentContent调用BlocksBlocks再逐块调用Block而Block的渲染又被拆分为RepeatedBlock、BlockWrapper、ComponentRef等子组件以规避 Svelte 与 React Server Components 的多重限制。运行环境注意事项Node v20 Apple Siliconpackages/sdks/README.md 与 packages/react/README.md 都记录了一个重要的兼容性问题SDK 在 Node 服务端依赖isolated-vm安全执行代码而该库在Node v20 M1 MacApple Silicon上存在兼容性问题。解决方法是给运行服务的命令加上环境变量NODE_OPTIONS--no-node-snapshot yarn dev若未提供该标志SDK 在 Apple Silicon Node v20 环境下会跳过使用isolated-vm。更多资源示例与官方站点examples/next-js-builder-site使用 Next.js 静态站点生成能力构建的 Builder 官方站点博客、文档与营销页是用 Builder 造 Builder的最佳参考examples/react-v2、examples/nextjs-app-dir-v2、examples/nextjs-pages-dir-v2Gen2 SDK 的官方示例分别对应 React Vite、Next.js App Router 与 Pages Router见 packages/sdks/output/react/README.mdexamples/next-js-cms-blog以 Builder 为 CMS 数据源的博客示例可直观体会页面/区块/CMS 数据三种集成形态pluginsAlgolia、Cloudinary、Contentful、Shopify 等官方插件展示如何扩展编辑器能力starters/create-builder一键生成新项目的启动器。如需快速体验可按照各 SDK 的安装命令如npm install builder.io/sdk-react与示例代码接入你自己的应用仓库本身是只读的所有接入与运行均在你的项目中进行。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考