前端UI组件设计系统【免费下载链接】semi-designA modern, comprehensive, flexible design system and React UI library, AI-friendly built-in.Provide 3000 Design Tokens, easy to build your design system. Make Semi Design to Any Design. Design to Code in one click项目地址https://gitcode.com/gh_mirrors/se/semi-design点击查看免费下载本指南以仓库内 semi-playground-for-ai/AGENTS.md 为骨架结合同一目录下的 README、Rspack 构建配置与源码完整讲解这个面向 AI 开发与测试的 Semi Design 组件沙箱如何用npm run dev / build / preview三条命令驱动一个不经过 npm 包、直接编译packages/源码并支持热更新的开发环境以及它背后的 alias 映射、React 19 源码切换 loader、SCSS Design Token 注入等实现细节。读完本文你可以独立复现这套「改源码即热更新」的组件验证工作流并理解其与 npm 包引用方式的行为差异。一、项目定位给 AI 的组件实验场semi-playground-for-ai/README.md 开宗明义这是一个「用于 AI 开发和测试 Semi Design 组件的 playground 项目」。与常规的 demo 项目不同它的三大特性决定了它的技术选型直接引用外部仓库packages/目录下的 Semi Design 源码而不是从 npm 拉取构建好的产物修改源码后实时热更新无需重新编译这使它天然适合 AI 在迭代组件时快速验证行为基于 Rspack 构建启动快速符合大仓库多包场景下对构建性能的要求。AGENTS.md 则是写给进入该项目的 AI 代理的「工作守则」声明 AI 应具备 JavaScript、Rspack 与 Web 应用开发能力写出可维护、高性能、可访问的代码随后给出三条核心命令并指向 Rspack 官方文档rspack.rs/llms.txt即面向 LLM 的机器可读文档。二、三条命令dev / build / previewAGENTS.md 中的命令与 package.json 的 scripts 一一对应底层全部由rspack/cli当前仓库锁定^1.6.8驱动命令底层调用用途npm run devrspack dev启动开发服务器支持热更新HMRnpm run buildrspack build构建生产环境产物npm run previewrspack preview本地预览生产构建结果完整的使用流程源自 README# 安装依赖 npm install # 启动开发服务器 npm run dev开发服务器行为在 rspack.config.ts 的devServer段有明确定义port: 0使用随机可用端口避免多个沙箱实例端口冲突hot: true开启模块热更新open: false不自动打开浏览器historyApiFallback: true支持前端路由历史模式static.directory指向public目录提供静态资源。生产构建则通过optimization段做了针对性优化rspack.SwcJsMinimizerRspackPlugin压缩 JSLightningCssMinimizerRspackPlugin压缩 CSSminimizerOptions.targets与编译目标一致并用splitChunks将react/react-dom单独拆成lib-reactchunkpriority 20、其余 node_modules 归入vendorspriority 10output.filename在开发环境为[name].js生产环境带[name].[contenthash:8].js缓存指纹performance对入口与资源设置 10MB 上限生产模式超限会给出 warning。三、核心机制alias 直连源码让「改源码即生效」沙箱不依赖 npm 包而是通过 Rspackresolve.alias把douyinfe/*命名空间指向仓库内的真实源码目录。配置采用精确匹配与前缀匹配两级策略见 rspack.config.ts// 精确匹配$指向入口文件避免读取 package.json 的 main/module 字段 douyinfe/semi-ui$: path.join(packagesDir, semi-ui/index.ts), douyinfe/semi-foundation$: path.join(packagesDir, semi-foundation/index.ts), douyinfe/semi-icons$: path.join(packagesDir, semi-icons/src/index.ts), douyinfe/semi-icons-lab$: path.join(packagesDir, semi-icons-lab/src/index.tsx), douyinfe/semi-illustrations$: path.join(packagesDir, semi-illustrations/src/index.ts), douyinfe/semi-animation$: path.join(packagesDir, semi-animation/index.ts), douyinfe/semi-animation-react$: path.join(packagesDir, semi-animation-react/index.ts), douyinfe/semi-animation-styled$: path.join(packagesDir, semi-animation-styled/index.ts), douyinfe/semi-json-viewer-core$: path.join(packagesDir, semi-json-viewer-core/src/index.ts), douyinfe/semi-theme-default$: path.join(packagesDir, semi-theme-default/scss/index.scss), // 前缀匹配用于深层导入 douyinfe/semi-ui: path.join(packagesDir, semi-ui), // ... 其余包同理这里有一个容易被忽略的关键设计带$的精确匹配直接指向各包的index.ts入口文件而不是让 Rspack 去解析package.json的main/module字段——这样既能保证入口确定性也避免了「解析到 dist 产物」从而绕过源码的情况。前缀匹配不带$则覆盖深层的子路径导入例如douyinfe/semi-ui/es/xxx这类写法也能落到源码目录。除此之外alias 还做了两个「环境隔离」react/jsx-runtime: path.join(require.resolve(react), .., jsx-runtime.js), react-dom: path.dirname(require.resolve(react-dom/package.json)), react: path.dirname(require.resolve(react/package.json)),即强制react/react-dom从 playground 自己的node_modules解析避免 React 实例被多副本化否则会引发 hooks 状态丢失、context 失效等经典双 React 问题。README 给出的「引用方式」也因此与 npm 包完全一致用户无感知import { Button, Input, Select } from douyinfe/semi-ui; import { IconSearch } from douyinfe/semi-icons;TypeScript 侧由 tsconfig.json 的paths做同样映射同时支持精确与*通配子路径并设置moduleResolution: bundler、jsx: react-jsx、strict: trueinclude覆盖[src, ../packages]保证编辑器的类型检查也直达源码。四、React 19 源码切换semi-react19-loader仓库的 loaders/semi-react19-loader.js 是一个自定义 webpack/Rspack loader负责把semi-ui源码中的 React 18 写法切换为 React 19 写法。其原理依赖源码内的特殊注释标记REACT_18_START ... REACT_18_END包裹 React 18 版本代码loader 直接整块删除REACT_19_START ... REACT_19_END包裹 React 19 版本代码默认处于注释状态loader 取消注释并移除每行开头的//。module.exports function semiReact19Loader(source) { // 删除 REACT_18 代码块包括标记 let result source.replace( /\/\*\s*REACT_18_START\s*\*\/[\s\S]*?\/\*\s*REACT_18_END\s*\*\//g, ); // 取消注释 REACT_19 代码块 result result.replace( /\/\*\s*REACT_19_START\s*\*\/([\s\S]*?)\/\*\s*REACT_19_END\s*\*\//g, (match, code) code.replace(/^\s*\/\/\s?/gm, ) ); return result; };在 rspack.config.ts 中semi-ui的 TS/JSX 文件会先经过semi-react19-loader再进入builtin:swc-loader注释写明 loader 自下而上执行因此 react19-loader 先跑{ test: /\.(jsx?|tsx?)$/, include: [path.resolve(packagesDir, semi-ui)], use: [ { loader: builtin:swc-loader, options: { /* swc 配置 */ } }, path.resolve(__dirname, loaders/semi-react19-loader.js), ] }swc 编译配置中jsc.transform.react采用runtime: automaticReact 17 的 JSX 转换并依据argv.mode判断development与refresh——开发模式自动注入 React Refresh 运行时这是热更新生效的关键一环。其他源码包semi-foundation、semi-icons 等则走第二条规则仅用 swc-loader 编译不经过该 loader。与此同时仓库根目录下还保留了 packages/semi-ui/react19-adapter.ts作为组件库自身面向 React 19 的适配层与 playground 的 loader 方案互为补充。五、Design Token 注入SCSS 编译与 npm 包行为对齐Semi Design 的样式体系依赖 SCSS 变量与 CSS 变量。为了让源码直编的行为与「npm 包」一致rspack.config.ts 的 sass-loader 通过additionalData做了三处注入const themeDir path.resolve(packagesDir, semi-theme-default/scss).replace(/\\/g, /); const scssVarStr import ${themeDir}/index.scss;\n; // SCSS 变量 const animationStr import ${themeDir}/animation.scss;\n; // 动画 const cssVarStr import ${themeDir}/global.scss;\n; // CSS 变量 // 只在 _base/base.scss 中注入 CSS 变量跟 npm 包行为一致 if (/_base[\\/]base\.scss/.test(loaderContext.resourcePath)) { return scssVarStr animationStr cssVarStr content; } return scssVarStr animationStr content;要点如下每个 SCSS 文件都会被注入semi-theme-default/scss/index.scssDesign Token 的 SCSS 变量与animation.scss保证任意组件的样式文件都能引用到 token 变量只有_base/base.scss额外注入global.scssCSS 变量这是因为 Semi 的 npm 包只在基础样式层输出 CSS 变量对应源码位置为 packages/semi-foundation/_base/base.scss 与 packages/semi-theme-default/scss 目录——沙箱刻意复刻了这一行为sassOptions.includePaths加入semi-theme-default/scss与semi-foundation让import能够按 Semi 的原始约定解析变量模块规则以type: css/auto输出样式配合experiments.css: true由 Rspack 原生处理 CSS 的提取与热更新。对应地src/main.tsx 中特别注释强调「不需要手动导入 global.scssCSS 变量会自动通过_base/base.scss注入」这正解释了上述机制对使用方的影响。六、实战示例在沙箱中验证 AIChatInput沙箱自带一个真实测试用例src/App.tsx主题是 AI 组件AIChatInput的「仅技能时的 placeholder 展示」行为正好契合本沙箱面向 AI 场景的定位import { AIChatInput } from douyinfe/semi-ui; import { useRef, useState } from react; // 从 constant.jsx 里拿的测试用 skills const skills [ { key: code, label: 代码生成, value: /代码生成, hasTemplate: true }, { key: translate, label: 翻译, value: /翻译, hasTemplate: false }, { key: summarize, label: 总结, value: /总结, hasTemplate: true }, { key: write-email, label: 写邮件, value: /写邮件, hasTemplate: false }, ];它覆盖了三个断言场景开启showPlaceholderWhenSkillOnly{true}时只有技能无输入内容也应显示 placeholder不开启该属性默认行为时仅技能不显示 placeholder通过defaultContent预置了默认技能${skills[0].value}时期望仍显示 placeholder。入口 index.html 提供#root挂载点src/main.tsx 使用ReactDOM.createRoot渲染App /。你可以在此基础上替换为自己的组件用例验证逻辑后执行npm run dev在浏览器中确认表现。七、构建模式判别与整体工作流rspack.config.ts 使用函数形式的defineConfig((env, argv) ...)通过argv.mode development可靠区分构建模式从而联动devtool开发环境cheap-module-source-map生产环境source-map、minimize、filename指纹、performance.hints开发模式关闭提示以及ReactRefreshPlugin的挂载isDev new ReactRefreshPlugin()配合plugins数组末尾的.filter(Boolean)剔除假值。browserslist 目标为[last 2 versions, 0.2%, not dead, Firefox ESR]。综合来看该沙箱的完整工作流是npm install安装 playground 自身的依赖React 18、Rspack、TypeScript 等见 package.json修改packages/下任意 Semi Design 包的源码、SCSS 或组件运行npm run devalias 直连源码 HMR 使改动即时生效无需编译产物复用douyinfe/*命名空间编写用例验证组件在真实源码下的行为需要交付验证时用npm run build产出带缓存指纹的生产包npm run preview本地预览。结语与适用场景semi-playground-for-ai 的价值在于把「Semi Design 组件源码迭代」与「AI 快速验证」衔接起来AI 代理依据 AGENTS.md 的约定进入项目用三条命令即可完成开发、构建与预览闭环而仓库的 alias 直连、react19-loader 与 SCSS token 注入三套机制保证了「源码即真身」与「行为同 npm 包」的一致性。这一模式同样适用于其他需要频繁改动底层组件库源码、又想获得秒级反馈的 monorepo 场景——如需了解其姊妹项目可对比 semi-live-for-ai 基于 React Live 的在线编辑器方案。赞分享前端UI组件设计系统【免费下载链接】semi-designA modern, comprehensive, flexible design system and React UI library, AI-friendly built-in.Provide 3000 Design Tokens, easy to build your design system. Make Semi Design to Any Design. Design to Code in one click项目地址https://gitcode.com/gh_mirrors/se/semi-design点击查看免费下载相关推荐Mastering Semi Design CodeHighlight基于 Prism 的 297 语言代码高亮组件实战与源码解析Mastering Semi Design CodeHighlight基于 Prism 的 297 语言代码高亮组件实战与源码解析 Semi Design 的前端UI组件设计系统Semi Design Anchor 锚点组件开发指南从基础用法到源码级原理剖析Semi Design Anchor 锚点组件开发指南从基础用法到源码级原理剖析 Anchor锚点是 Semi Design React UI 库中用于构前端UI组件设计系统Rspack热更新原理提升开发效率的黑科技Rspack热更新原理提升开发效率的黑科技 在现代化的前端开发中 Rspack热更新 技术已经成为提升开发效率的关键利器。作为基于Rust构建的高性能构建工开发工具前端上一篇旧Mac焕新指南零成本制作macOS启动盘全攻略下一篇10倍效率提升的歌词管理工具163MusicLyrics破解音乐爱好者的痛点创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
