Builder.io Svelte SDK 使用指南从安装到 SvelteKit 集成实战【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder本指南以 packages/sdks/output/svelte/README.md 为骨架系统讲解 Builder.io Svelte SDK 的定位、生成方式、安装步骤与 SvelteKit 集成方案。你将掌握builder.io/sdk-svelte的核心 APIContent、fetchOneEntry、isPreviewing、getBuilderSearchParams的真实用法并了解该 SDK 多环境构建浏览器/Node/边缘运行时的底层机制。一、SDK 定位由 Mitosis 生成的 Svelte 渲染层Builder.io Svelte SDK 是 Builder.io 新一代 SDK 体系中的一员它的核心职责是在 Svelte 应用中渲染 Builder.io 可视化编辑器产出的内容并将自定义组件接入可视化编辑流程。关键信息来自 packages/sdks/output/svelte/README.md该 SDK 由 Mitosis 自动生成并非手写维护Mitosis 的源码位于仓库的 packages/sdks/src生成产物输出到packages/sdks/output/目录同一套 Mitosis 源码同时生成 React、Vue 3、Svelte、SolidJS、Angular、Qwik、React Native、Next.js 等多个框架的 SDK见 packages/sdks/README.md。从源码结构看Content组件的核心实现位于 packages/sdks/src/components/content/content.lite.tsx其类型定义在 packages/sdks/src/components/content/contentProps.types.ts。这些.lite.tsx文件就是 Mitosis 的框架无关源码Svelte 版 SDK 是它的编译产物。二、Feature Support如何核对 SDK 功能状态原文档明确说明要查看该 SDK 的功能实现状态请查看 Feature Implementation 表格。该表格位于 packages/sdks/README.md 的 # Feature Implementation 一节涵盖了各框架 SDK 的功能对比包括Available Features各 SDK 已实现的功能列表Builder Blocks各框架可用的 Builder 基础块Builder Widgets各框架可用的 Builder 小组件。仓库目前持续为各 SDK 实现新功能因此在使用前核对功能表是一个值得养成的习惯——尤其是当你依赖某个较新的 Builder 块Block或组件时应以该表格为准确认 Svelte 版是否已支持。三、快速开始安装与最小示例3.1 安装SDK 的 npm 包名为builder.io/sdk-svelte在 Svelte 或 SvelteKit 项目中直接安装即可npm install builder.io/sdk-svelte从 packages/sdks/output/svelte/package.json 可以看到当前版本号为5.2.11包类型为type: module即 ESM 优先peerDependencies要求svelte: ^4.1.2适用于 Svelte 4运行时依赖仅isolated-vm: ^6.0.0用于在服务端安全执行代码开发依赖中包含builder.io/sdksworkspace 内部共享源码包与sveltejs/kit、vite等构建工具链。3.2 多环境构建产物该 SDK 通过svelte-package为三种运行环境分别打包见 package.json 的scripts段构建目标命令产物目录适用场景Browserbuild:browserlib/browser/浏览器端渲染Nodebuild:nodelib/node/Node.js 服务端SSREdgebuild:edgelib/edge/边缘运行时Deno、Bun、Cloudflare Workers、Netlify Edge 等包入口通过exports字段按运行环境自动分发svelte/browser走lib/browser/index.jsnode/electron走lib/node/index.jsedge-routine、workerd、deno、lagon、netlify、edge-light、bun等走lib/edge/index.js。这意味着同一个包可以在 SSR、静态生成和边缘函数等多种部署形态下工作。注意SDK 依赖isolated-vm来在 Node 服务端安全执行代码。在 Node v20 Apple SiliconM1机器上存在兼容性问题运行服务端时需要设置环境变量NODE_OPTIONS--no-node-snapshot否则 SDK 会跳过isolated-vm详见 packages/sdks/README.md 的 Node v20 M1 Macs Support 一节。四、Fetch 行为说明原文档特别强调该包使用fetch。在源码中这一行为由 packages/sdks/src/functions/get-content/index.ts 实现_fetchContent内部调用generateContentUrl(options)构造请求 URL并通过options.fetch ?? fetch使用全局fetch发起请求默认实现位于../get-fetch.js。也就是说SDK 没有内置自己的 HTTP 客户端而是复用运行环境的标准fetch——这也解释了为什么它能在浏览器、Node 和边缘运行时之间无缝切换。五、SvelteKit 集成实战原文档指向官方示例仓库 examples/svelte/sveltekit该示例完整演示了 SvelteKit 下如何接入 SDK。以下结合示例源码逐层拆解。5.1 准备 API Key在 examples/svelte/sveltekit/src/apiKey.js 中导出公开 API Key// TODO: enter your public API key export const BUILDER_PUBLIC_API_KEY f1a790f8c3204b3b8c5c1795aeac4660; // ggignore操作流程对应示例 README登录 Builder.io从账户页面复制你的 API Key将其填入src/apiKey.js中的BUILDER_PUBLIC_API_KEY打开 Builder.io Visual Editor选择名为 page 的模型model在编辑器右上角预览地址栏输入http://localhost:3000在 Layers 面板中拖入组件页面即会实时出现在编辑器中。5.2 服务端加载内容page.server.jsSvelteKit 的load函数在服务端运行负责拉取 Builder 内容。示例位于 examples/svelte/sveltekit/src/routes/[...catchall]/page.server.jsimport { fetchOneEntry, getBuilderSearchParams } from builder.io/sdk-svelte; import { BUILDER_PUBLIC_API_KEY } from ../../apiKey; /** type {import(./$types).PageServerLoad} */ export async function load(event) { // fetch your Builder content const content await fetchOneEntry({ model: page, apiKey: BUILDER_PUBLIC_API_KEY, options: getBuilderSearchParams(event.url.searchParams), userAttributes: { urlPath: event.url.pathname || / } }); return { content }; }这里用到了两个核心 APIfetchOneEntry(options)按条件获取单条 Builder 内容model 匹配的第一条。源码实现位于 packages/sdks/src/functions/get-content/index.ts其内部实际是fetchEntries({ ...options, limit: 1 })的封装取results数组的第一项无结果时返回nullgetBuilderSearchParams(url.searchParams)将 URL 查询参数转换为 SDK 请求参数。源码见 packages/sdks/src/functions/get-builder-search-params/index.ts其注释明确提示该函数一般并不需要推荐改用isPreviewing()来判断是否处于预览模式见下节userAttributes.urlPath传入当前页面路径用于 Builder 的个性化与目标匹配Targeting逻辑。5.3 客户端渲染与自定义组件page.svelte页面组件位于 examples/svelte/sveltekit/src/routes/[...catchall]/page.sveltescript import Counter from ../../lib/Counter.svelte; import { isPreviewing, Content } from builder.io/sdk-svelte; import { BUILDER_PUBLIC_API_KEY } from ../../apiKey; // Create an array of your custom components and their properties const CUSTOM_COMPONENTS [ { component: Counter, name: Counter, inputs: [ { name: name, type: string, defaultValue: hello }, { name: count, type: number, defaultValue: 0 } ] } ]; // this data comes from the function in page.server.js, which runs on the server only export let data; // we want to show unpublished content when in preview mode. const canShowContent data.content || isPreviewing(); /script main h1Welcome to SvelteKit/h1 divBelow is your Builder Content:/div {#if canShowContent} divpage Title: {data.content?.data?.title || Unpublished}/div Content modelpage content{data.content} apiKey{BUILDER_PUBLIC_API_KEY} customComponents{CUSTOM_COMPONENTS} / {:else} Content Not Found {/if} /main要点解析Content组件是渲染入口接收model内容模型名、content服务端加载到的数据、apiKey公开 API Key以及customComponents自定义组件注册表等 propsisPreviewing()当在 Builder.io 可视化编辑器中预览时返回true。这里用data.content || isPreviewing()的组合判断——发布内容用服务端数据预览时则允许显示未发布内容customComponents注册协议每个自定义组件需要声明componentSvelte 组件本身、name在编辑器中显示的名称和inputs可编辑的属性列表含name、type、defaultValue。这样 Builder 编辑器就能识别并可视化编辑该组件自定义组件示例Counter.svelte位于 examples/svelte/sveltekit/src/lib/Counter.svelte是一个带弹跳数字动画的计数器其name、count两个属性正好对应上面的inputs注册。5.4 运行与构建示例 README 给出的命令# install dependencies npm install # serve with hot reload at localhost:3000 npm run dev # or start the server and open the app in a new browser tab npm run dev -- --open生产构建与预览npm run build npm run preview部署到不同平台时可能需要为 SvelteKit 安装对应的 adapter 供参考。六、从源码理解 SDK 的工作方式虽然 Svelte 版 SDK 是编译产物packages/sdks/output/svelte/目录下只有工程配置实际源码由 Mitosis 从 packages/sdks/src 生成但我们可以通过共享源码理解其内部原理内容获取链路fetchOneEntry→fetchEntries→_fetchContent→generateContentUrlfetch最终请求 Builder 的 Content Delivery API返回BuilderContent结构见 packages/sdks/src/functions/get-content/index.ts测试保障packages/sdks/src/functions/get-content/index.test.ts 对fetchEntries/fetchOneEntry的行为进行了单元测试可作为理解参数语义的补充材料内容渲染组件Content组件的 Mitosis 源码在 packages/sdks/src/components/content/content.lite.tsx其 props 类型在 packages/sdks/src/components/content/contentProps.types.ts想要深入了解可用属性时可查阅这两处。七、小结Builder.io Svelte SDK 以 Mitosis 单一源码为基础为 Svelte 生态提供了与 React、Vue、Qwik 等框架对等的 Builder.io 内容渲染能力。通过npm install builder.io/sdk-svelte即可接入配合fetchOneEntry服务端取数、Content渲染、isPreviewing预览模式与customComponents自定义组件注册四个核心 API即可在 SvelteKit 中完成从内容拉取到可视化编辑的完整闭环。功能支持状态、版本兼容性与 Node v20 环境注意事项请以 Feature Implementation 表格 和 package.json 为准。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考