本文介绍如何构建一个类似 shadcn 的、源码可直接安装到项目中并自由修改的组件库，核心是通过 npm 包发布 + 本地源码分发实现高度可定制性。
本文介绍如何构建一个类似 shadcn 的、源码可直接安装到项目中并自由修改的组件库，核心是通过 npm 包发布 + 本地源码分发实现高度可定制性。
要打造一个真正“可安装、可编辑、可定制”的组件库（如 shadcn-ui），关键不在于打包成黑盒式二进制包，而在于将组件源码以模块化形式发布为 npm 包，让开发者能直接 npm install 后在项目中看到并修改原始 JSX/TSX 文件。
✅ 正确做法：发布为 ESM + TypeScript 源码包
- 在
package.json中设置：{ "name": "@yourorg/ui", "version": "1.0.0", "main": "./dist/index.js", "types": "./dist/index.d.ts", "exports": { ".": { "import": "./dist/index.js", "require": "./dist/index.js" }, "./button": { "import": "./src/components/button/index.tsx", "require": "./src/components/button/index.tsx" }, "./input": { "import": "./src/components/input/index.tsx", "require": "./src/components/input/index.tsx" } }, "files": ["src", "dist", "types", "package.json", "README.md"], "typesVersions": { "*": { "*": ["types/*"] } } } - 使用
tsc --build或tsup构建类型声明与 ESM/CJS 兼容输出，但务必保留src/目录并包含在files字段中——这是实现“源码可编辑”的前提。
? 安装后即可直接修改：
npm install @yourorg/ui # 安装后，node_modules/@yourorg/ui/src/components/button/ 下即为可编辑源码
你甚至可通过 pnpm link 或 npm link 在本地开发时实时调试；配合 @types/react 和严格 tsconfig，确保类型安全不丢失。
⚠️ 注意事项：
- ❌ 避免仅发布编译后代码（如只含
dist/）——这会让用户无法修改逻辑或样式； - ✅ 推荐使用
"type": "module"+.mjs或现代 ESM 路径映射，提升 tree-shaking 与路径解析准确性； - ? 若需 CLI 支持（如 shadcn 的
npx shadcn-ui@latest add button），需额外开发基于create-xxx或execa的命令行工具，读取模板并复制源码到项目components/目录——这才是 shadcn “复制而非安装”的本质；但本方案更轻量、更透明，适合设计系统团队统一维护源码。
总结：真正的可定制组件库 = 源码即包 + 显式路径导出 + 类型完备 + 构建友好。它不是“不可变依赖”，而是“可复刻、可演进的设计契约”。
