企业官网建设流程全解析

React 19 组件库设计实践：拆解 sample-monorepo 的 @sample/components 包

【免费下载链接】sample-monorepoSample monorepo setup with npm workspaces and typescript project references项目地址: https://gitcode.com/gh_mirrors/sa/sample-monorepo

React 19 组件库的设计，不只是写几个组件那么简单。在 sample-monorepo 这个 npm workspaces + TypeScript project references 构成的示例仓库中，@sample/components包向我们完整展示了：一个可独立发布、又能被同仓库应用平滑消费的 React 19 组件库，究竟该如何组织源码、配置依赖与构建产物。本文将以这个真实项目为蓝本，带你从零理解组件库包的结构、入口、类型安全与发布机制，帮你快速上手自己的组件库设计。

为什么用 monorepo 来管理 React 组件库

传统多仓库模式下，组件库和应用各自维护一套devDependencies，版本极易漂移。sample-monorepo 把@sample/components、@sample/app、@sample/server放进同一个仓库，通过根目录 package.json 的workspaces字段统一管理依赖，再配合 lerna.json 做独立版本发布，一次npm i就能自动把包与包之间软链起来，跨包开发零成本。

@sample/components 包的核心文件结构

组件库的骨架非常清晰，建议新手直接对照阅读：

• packages/components/package.json：包元信息、导出入口、依赖声明
• packages/components/src/main.tsx：组件本体与类型定义
• packages/components/src/index.ts：统一的对外出口
• packages/components/src/tsconfig.json：包级 TypeScript 配置

最小可用组件库的导出设计

一个合格的组件库，对外暴露的 API 要克制。@sample/components的做法是：在 main.tsx 中定义MainProps接口与Main组件，然后在 index.ts 里用一行export * from "./main.js"统一导出。这样使用者只需import { Main } from "@sample/components"，完全不需要关心内部文件布局。React 19 下，组件以React.FC+ 强类型 props 呈现，配合verbatimModuleSyntax严格区分类型导入，类型体验接近原生。

peerDependencies 的正确用法：React 版本交给消费者

组件库最忌讳把 React 打进自己的依赖里。该包的 package.json 把react: >=18声明为peerDependencies，只要求宿主环境提供 React，自己不重复安装，既避免版本冲突，也减小包体积。在 React 19 时代，这个设计对组件库尤其重要，能让你一套代码同时兼容 18/19 两个大版本。

TypeScript project references 如何串联整个仓库

根目录的 tsconfig.json 是一个"解决方案"配置，通过references指向三个包的src目录；而每个包内部的 tsconfig.json 继承根部的 tsconfig.base.json，开启composite: true实现增量编译。于是npm run build（即tsc --build）会按依赖顺序自动构建所有包，产物输出到各自的dist目录，配合declaration与declarationMap生成完整的.d.ts类型文件，让消费方拿到的不只是 JS，还有精确的类型提示。

包消费与独立发布的平衡术

在 app.tsx 中，应用通过普通依赖"@sample/components": "^1.0.0"引入组件库，workspaces 会自动链接到本地源码。同时，包的 package.json 通过exports字段精确控制发布后哪些入口可用，用files白名单打包dist与src（排除测试与构建缓存），配合prepack脚本自动先构建再打包，最后npx lerna publish即可按需发布到 npm。这套"本地开发链接、发布独立版本"的机制，正是组件库工程化的精髓。

用 node:test 守护组件库质量

组件库的测试同样值得借鉴：项目没有引入重型测试框架，而是直接用 Node 内置的node:test编写用例（如 test.test.ts），配合--enable-source-maps在报错时直接映射回 TypeScript 源码，轻量且零额外依赖，非常适合组件库这类以纯函数与渲染逻辑为主的场景。

结语：三步照抄这套组件库设计

如果你想在自己的 React 19 项目中落地组件库，只需三步：第一，用 npm workspaces 建好 monorepo 骨架；第二，把 React 放进peerDependencies，用exports收紧对外入口；第三，开启 TypeScript project references 让构建按依赖自动编排。把这套@sample/components的结构跑通，你的组件库就已经具备了专业工程化的雏形。想要快速对照源码，git clone https://gitcode.com/gh_mirrors/sa/sample-monorepo后执行npm i && npm run build即可。

【免费下载链接】sample-monorepoSample monorepo setup with npm workspaces and typescript project references项目地址: https://gitcode.com/gh_mirrors/sa/sample-monorepo