Builder 仓库 React SDK 上手模板解析Vite React 18 TypeScript 最小化工程与 ESLint 类型感知配置指南【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder本文围绕packages/sdks/snippets/react/README.md这份模板说明文档展开该模板提供了一套让 React 在 Vite 中以 HMR热模块替换运行的最小化工程并附带基础 ESLint 规则。读完本文你既能掌握官方两个 Fast Refresh 插件Babel 版与 SWC 版的取舍、生产环境启用类型感知 Lint 规则的完整配置方法也能看清这套模板在 Builder 单仓库中作为builder.io/sdk-react官方示例应用snippet被接入 monorepo 与 e2e 测试体系的完整链路。一、模板定位React Vite 的最小化可用工程原文档 README.md 开宗明义该模板提供了一套最小化配置让 React 在 Vite 中跑起来并自带 HMR 与若干 ESLint 规则。它源自 Vite 官方的 react-ts 脚手架本仓库将其收录为snippet/react工作区包作为 Builder 新一代 React SDK 的演示与集成验证载体。结合 package.json 可以看到模板的完整技术栈与版本基线适用前提Node 环境可运行 Vite 5使用 yarn workspaces 管理类别依赖版本约束说明运行依赖react/react-dom^18.2.0React 18 客户端渲染运行依赖react-router-dom^6.24.1模板在此之上扩展了路由层见第五节运行依赖builder.io/sdk-reactworkspace:*工作区内链接的 Builder React SDK开发依赖vite^5.2.0构建与 HMR 开发服务器开发依赖vitejs/plugin-react^4.2.1Babel 路线的 React 插件开发依赖typescript^5.2.2严格模式编译检查开发依赖eslint/typescript-eslint/*^8.57.0/^7.2.0Lint 体系入口 HTML index.html 保持模板原样div idroot挂载点 typemodule方式加载src/main.tsx页面标题仍保留脚手架默认的 “Vite React TS”。1.1 两个官方 Fast Refresh 插件原文档明确指出目前有两个官方插件可用区别在于 Fast Refresh快速刷新的底层编译器vitejs/plugin-react基于Babel实现 Fast Refresh。本仓库实际采用的就是它vite.config.ts 只有寥寥几行import react from vitejs/plugin-react; import { defineConfig } from vite; export default defineConfig({ plugins: [react()], });vitejs/plugin-react-swc基于SWCRust 编写的编译器实现 Fast Refresh通常用于追求更快编译/刷新速度、并愿意用 SWC 替换 Babel 转换链路的场景。从源码结构看当前 snippet 工程选择了 Babel 路线devDependencies中只安装了vitejs/plugin-react未引入 SWC 插件这是 Vite react-ts 模板的默认选项若你的项目更看重大型代码库下的冷启动与保存耗时可评估切换到 SWC 版本插件两者对上层 React 代码是透明的。二、模板的文件结构与 TypeScript 工程配置模板采用 TypeScript 5.2 的“项目引用”project references双配置布局这是后文启用类型感知 ESLint 的关键前提。tsconfig.json主配置覆盖src/{ compilerOptions: { target: ES2020, useDefineForClassFields: true, lib: [ES2020, DOM, DOM.Iterable], module: ESNext, skipLibCheck: true, /* Bundler mode */ moduleResolution: bundler, allowImportingTsExtensions: true, resolveJsonModule: true, isolatedModules: true, noEmit: true, jsx: react-jsx, /* Linting */ strict: true, noUnusedLocals: true, noUnusedParameters: true, noFallthroughCasesInSwitch: true }, include: [src], references: [{ path: ./tsconfig.node.json }] }tsconfig.node.json副配置只覆盖 Vite 配置文件本身{ compilerOptions: { composite: true, skipLibCheck: true, module: ESNext, moduleResolution: bundler, allowSyntheticDefaultImports: true, strict: true }, include: [vite.config.ts] }几个值得注意的点moduleResolution: bundlerisolatedModules: true对应 Vite 这类打包器模式与package.json中type: module相配合strict: true及noUnusedLocals、noUnusedParameters模板即默认开启严格检查build脚本里的tsc步骤会在构建前做一次完整类型检查见下文 scriptsreferences指向tsconfig.node.json这一“主 节点”双配置组合与后文 ESLint 的parserOptions.project数组精确对应。2.1 npm scripts开发、构建、Lint 与测试package.json 中的脚本完整继承了 Vite 模板的四个命令并追加了一个面向 Builder monorepo 的测试入口脚本命令作用devvite启动带 HMR 的开发服务器buildtsc vite build先做 TS 全量类型检查再产出dist/linteslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0零容忍告警的全量 Lintservevite preview本地预览构建产物testSERVER_NAMEreact yarn g:nx test:snippet sdk/tests通过 Nx 运行 SDK 针对本 snippet 的测试其中g:nx是根仓库 package.json 定义的全局脚本g:nx: cd $INIT_CWD nx——它保证 Nx 命令始终在触发它的工作区目录执行。也就是说这个 Vite 模板并不是孤立示例它以SERVER_NAMEreact为标识接入统一测试流与 packages/sdks/e2e/ 下各框架的 e2e 工程react、sveltekit、nuxt 等并列。packages/sdks/README.md 说明了背景仓库中的新一代 SDK 由 Mitosis 生成各框架 SDK 产物位于output/目录而snippets/正是各框架的“快速上手示例代码”。2.2 当前生效的 ESLint 基线配置模板“附带的一些 ESLint 规则”在本仓库落地为 .eslintrc.cjsmodule.exports { root: true, env: { browser: true, es2020: true }, extends: [ eslint:recommended, plugin:typescript-eslint/recommended, plugin:react-hooks/recommended, ], ignorePatterns: [dist, .eslintrc.cjs], parser: typescript-eslint/parser, plugins: [react-refresh], rules: { react-refresh/only-export-components: [ warn, { allowConstantExport: true }, ], }, };可以对照原文档理解它的定位这里使用的是plugin:typescript-eslint/recommended非类型感知档位尚未配置parserOptions.project。它恰好是原文档“Expanding the ESLint configuration”一节所描述的扩展前起点下一节即给出扩展目标形态。三、扩展 ESLint 配置启用类型感知 Lint 规则原文档给出的完整实操建议是如果你正在开发生产应用推荐更新配置以启用类型感知type-awarelint 规则。三步操作如下可整体复制执行。3.1 第一步配置顶层parserOptions原文档给出的推荐配置完整保留export default { // other rules... parserOptions: { ecmaVersion: latest, sourceType: module, project: [./tsconfig.json, ./tsconfig.node.json], tsconfigRootDir: __dirname, }, };参数逐项说明ecmaVersion: latest解析器按最新 ECMAScript 语法处理源码避免新版语法触发误报sourceType: module以 ES Module 方式解析与package.json的type: module一致project: [./tsconfig.json, ./tsconfig.node.json]告诉typescript-eslint同时加载本模板的两个 tsconfig这正是第二节中主配置 节点配置的项目引用组合覆盖了src/与vite.config.ts全部代码范围类型感知规则据此获得真实的类型信息tsconfigRootDir: __dirname将上述相对路径的解析基准锚定在 ESLint 配置文件所在目录。3.2 第二步升级 TypeScript 插件档位将 extends 中的plugin:typescript-eslint/recommended替换为以下二者之一plugin:typescript-eslint/recommended-type-checked推荐档位的类型感知版覆盖常见类型错误模式plugin:typescript-eslint/strict-type-checked严格档位的类型感知版规则更激进适合对代码质量要求极高的生产项目。3.3 第三步可选的样式档与 React 官方插件可选追加plugin:typescript-eslint/stylistic-type-checked类型感知的代码风格规则安装eslint-plugin-react并在extends列表中加入plugin:react/recommended与plugin:react/jsx-runtime后者适配本模板 tsconfig 中的jsx: react-jsx新 JSX 转换运行时。落地提示把 3.1 的parserOptions合入现有 .eslintrc.cjs 时注意project数组必须与磁盘上真实存在的 tsconfig 文件一致——本模板恰好只有tsconfig.json与tsconfig.node.json两份可直接照搬原文档示例。启用类型感知后lint脚本--max-warnings 0会把所有类型相关告警都变成 CI 级别的硬约束。四、模板之上作为 Builder SDK 示例应用的实战内容原文档描述的是“最小化模板”而本仓库在这个模板骨架之上长出了完整的 SDK 演示应用。以下从源码结构看它的组织方式可作为接入builder.io/sdk-react的参照。4.1 路由层一个 Vite SPA 演示十几个 SDK 场景src/main.tsx 使用react-router-dom的createBrowserRouter注册了全部演示路由ReactDOM.createRoot挂载在index.html的#root上路径组件演示主题/*兜底IntegratingPages快速开始按urlPath拉取并渲染页面/homeHomepage固定 modelhomepage拉取内容/live-previewLivePreviewBlogData编辑器实时预览订阅/query-cheatsheetQueryCheatsheet17 种查询操作符一览/targeted-page、/targeted-page-set-attributesTargetedPage等定向targeting与用户属性/custom-child、/advanced-child、/editable-region自定义组件系列注册自定义 React 组件承接 Builder 块/blogs/:handle、/products/:id、/product/category/:handle、/marketing-event、/landing-page、/announcements/:id各 blueprint 组件博客、商品、营销页等蓝图4.2 快速开始fetchOneEntry Content isPreviewingIntegratingPages.tsx文件头注释自述 “Quickstart snippet”展示了 SDK 的三个核心 API 协作const BUILDER_API_KEY ee9f13b4981e489a9a1209887695ef2b; const MODEL_NAME page; useEffect(() { fetchOneEntry({ model: MODEL_NAME, apiKey: BUILDER_API_KEY, userAttributes: { urlPath: window.location.pathname, // 用当前路径去匹配 Builder 中的页面 }, }) .then((content) { if (content) setContent(content); setNotFound(!content); }) .catch((err) console.log(Oops: , err)); }, []); // 未找到页面且不在预览态时渲染你自己的 404 if (notFound !isPreviewing()) { return div404/div; } return Content content{content} model{MODEL_NAME} apiKey{BUILDER_API_KEY} /;三个要点fetchOneEntry负责按 model 用户属性取回单条内容isPreviewing()用于在 Builder 可视化编辑器预览期间跳过 404 分支预览态下即使线上还没有该页面也要照常渲染编辑器内容Content负责把取回的内容渲染成 React 组件树。Homepage.tsx 是同一模式的极简变体不带urlPath固定取homepagemodel。4.3 实时预览subscribeToEditorLivePreviewBlogData.tsx 演示了不发布内容即可在浏览器中实时预览的订阅模式useEffect中调用subscribeToEditor({ model, apiKey, callback })持续接收编辑器推送的内容并在清理函数里执行返回的unsubscribe组件内直接读取content?.data?.title / author / handle渲染。4.4 查询速查表与自定义组件query-cheatsheet/index.tsx 以表格形式并发演示了 17 个查询操作符$eq、$gt、$gte、$in、$lt、$lte、$ne、$nin、$and、$not、$or、$nor、$exists、$type、$elemMatch、$regex、$options子目录下每个操作符对应一个独立请求文件CustomColumns.tsx 演示如何注册自定义组件导出RegisteredComponentname、component、shouldReceiveBuilderProps: { builderBlock: true }、inputs中以type: uiBlocks声明可拖入的子块槽位组件内部用Blocks blocks path parent渲染 Builder 块——即“用你自己的 React 组件包裹可视化编辑区域”的标准做法。五、小结这份snippet/react模板是标准 Vite react-ts 脚手架最小化工程、HMR、基础 ESLint 规则并明确了 Babelvitejs/plugin-react与 SWCvitejs/plugin-react-swc两条 Fast Refresh 路线生产环境扩展 Lint 的核心动作是给 ESLint 增加parserOptionsproject指向./tsconfig.json与./tsconfig.node.jsontsconfigRootDir: __dirname再把 TS 插件档位切到recommended-type-checked/strict-type-checked可选叠加stylistic-type-checked与eslint-plugin-react在 Builder 仓库语境下该模板进一步演化为builder.io/sdk-react的官方示例应用以SERVER_NAMEreact接入 Nx 测试流test脚本路由层覆盖了快速开始、实时预览、查询速查表、定向与自定义组件注册等真实接入场景可直接作为在 Vite 项目中集成 Builder React SDK 的蓝本。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考