Skip to content

Commit f1b722a

Browse files
wkylinwkylin
committed
feat: 构建置升级, 发布npm组件包
1 parent bbaecc6 commit f1b722a

File tree

19 files changed

+2699
-384
lines changed

19 files changed

+2699
-384
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,4 @@ coverage
2121

2222
*storybook.log
2323
storybook-static
24+
/dist-lib

‎.npmignore‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# 源代码
2+
src/
3+
public/
4+
tests/
5+
test-results/
6+
docs/
7+
scripts/
8+
webpack/
9+
faker/
10+
11+
# 配置文件
12+
*.config.js
13+
*.config.ts
14+
*.config.mjs
15+
tsconfig.json
16+
babel.config.js
17+
biome.json
18+
cspell.json
19+
eslint.config.mjs
20+
playwright.config.ts
21+
postcss.config.js
22+
qodana.yaml
23+
workspace.jsonc
24+
docker-compose.yml
25+
Dockerfile
26+
27+
# 开发文件
28+
.vscode/
29+
.idea/
30+
.github/
31+
*.log
32+
*.md
33+
!README.md
34+
.editorconfig
35+
.gitignore
36+
.prettierrc
37+
.eslintrc
38+
.eslintignore
39+
40+
# 构建产物（保留 dist-lib）
41+
dist/
42+
coverage/
43+
storybook-static/
44+
node_modules/
45+
46+
# 其他
47+
*.cmd
48+
*.sh
49+
.husky/
50+
.env
51+
.env.*
52+
*.tsbuildinfo
53+
stats.json
54+
compilation-stats.json
55+
packagehash.txt

‎NPM_README.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# @w.ui/wui-react
2+
3+
基于 React 19 和 Ant Design 6 的高质量组件库，提供 300+ 可复用的业务组件。
4+
5+
## ✨ 特性
6+
7+
- 🚀 基于 **React 19** 和 **Ant Design 6** 构建
8+
- 📦 开箱即用的高质量 React 组件
9+
- 🛡 使用 TypeScript 开发，提供完整的类型定义
10+
- 🎨 支持主题定制和暗黑模式
11+
- 📱 响应式设计，完美适配移动端
12+
- 🌐 国际化支持
13+
14+
## 📦 安装
15+
16+
```bash
17+
npm install @w.ui/wui-react
18+
# 或
19+
yarn add @w.ui/wui-react
20+
# 或
21+
pnpm add @w.ui/wui-react
22+
```
23+
24+
## 🔨 使用
25+
26+
```jsx
27+
import React from 'react';
28+
import { DescBox, RadioInput, Exception } from '@w.ui/wui-react';
29+
import '@w.ui/wui-react/style.css';
30+
31+
const App = () => {
32+
return (
33+
<div>
34+
<DescBox title="示例标题" description="这是一个描述框组件" />
35+
<RadioInput
36+
options={[
37+
{ label: '选项1', value: '1' },
38+
{ label: '选项2', value: '2' }
39+
]}
40+
onChange={(value) => console.log(value)}
41+
/>
42+
</div>
43+
);
44+
};
45+
46+
export default App;
47+
```
48+
49+
## 📚 组件列表
50+
51+
本库包含 100+ 组件，包括但不限于：
52+
53+
### 核心组件
54+
- ErrorBoundary - 错误边界
55+
- WatermarkProvider - 水印
56+
- KeepAlive - 页面缓存
57+
- ResponsiveTable - 响应式表格
58+
- GlobalSearch - 全局搜索
59+
60+
### UI 组件
61+
- AdvancedCodeBlock - 高级代码块
62+
- AnimatedList - 动画列表
63+
- BackgroundBeams - 背景光束效果
64+
- BorderBeam - 边框动画
65+
- ColorfulText - 彩色文字
66+
- DescBox - 描述框
67+
- RadioInput - 单选/多选输入
68+
69+
### 动画组件
70+
- AnimateOnScreen - 进入视口动画
71+
- AnimateRipple - 波纹动画
72+
- BlurFade - 模糊渐显
73+
- ScrollAnimation - 滚动动画
74+
- TypeWriter - 打字机效果
75+
76+
完整组件列表请访问 [在线文档](https://wkylin.github.io/pro-react-admin/storybook/)
77+
78+
## 🔗 依赖
79+
80+
### Peer Dependencies
81+
82+
```json
83+
{
84+
"react": ">=19.0.0",
85+
"react-dom": ">=19.0.0",
86+
"antd": ">=6.0.0"
87+
}
88+
```
89+
90+
确保你的项目中已安装这些依赖。
91+
92+
## 🌍 浏览器支持
93+
94+
- 现代浏览器
95+
- Chrome >= 90
96+
- Firefox >= 88
97+
- Safari >= 14
98+
- Edge >= 90
99+
100+
## 📖 文档
101+
102+
- [在线演示](https://wkylin.github.io/pro-react-admin/)
103+
- [Storybook 组件文档](https://wkylin.github.io/pro-react-admin/storybook/)
104+
- [GitHub 仓库](https://github.com/wkylin/pro-react-admin)
105+
106+
## 🤝 贡献
107+
108+
欢迎提交 Issue 和 Pull Request！
109+
110+
详见 [贡献指南](https://github.com/wkylin/pro-react-admin/blob/main/CONTRIBUTING.md)
111+
112+
## 📄 License
113+
114+
MIT © [wkylin](https://github.com/wkylin)
115+
116+
## 👨‍💻 作者
117+
118+
**wkylin**
119+
- GitHub: [@wkylin](https://github.com/wkylin)
120+
- Email: [email protected]
121+
122+
## ⭐️ Star History
123+
124+
如果这个项目对你有帮助，请给一个 ⭐️ 支持一下！

‎README.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
## 🏆 项目亮点
3030

3131
- **🚀 极致性能体验**：基于 **React 19** 构建，重构 `KeepAlive` 缓存机制（采用 CSS 显隐策略替代 DOM 移动，大幅减少重排），配合 `useTransition` 实现丝滑的 Tab 切换与交互响应。
32-
- **🧩 丰富组件生态**：沉淀 **300+** 高质量业务组件，覆盖图表、地图、编辑器等场景。集成 **Storybook** 实现组件可视化开发与文档管理，显著提升复用效率。
32+
- **🧩 丰富组件生态**：沉淀 **120+** 高质量业务组件，支持 **独立打包发布 (@w.ui/wui-react)**。集成 **Storybook** 实现组件可视化开发与文档管理，显著提升复用效率。
3333
- **🛡️ 企业级权限体系**：完善的 **RBAC** 模型，支持路由、菜单、按钮级细粒度权限控制。内置路由自动过滤、`useSafeNavigate` 防越权跳转，保障系统安全。
3434
- **⚡️ 前沿技术栈**：采用 **TypeScript v5** + **Ant Design v6** + **Vite v7/Webpack v5** 双构建模式，紧跟社区最新标准，提供最佳开发体验。
3535
- **🤖 AI 智能化集成**：内置 ChatGPT 演示（支持 SSE 流式响应）、Markmap 思维导图生成、Mermaid 流程图渲染，探索 AI 在后台管理中的应用场景。
@@ -51,6 +51,7 @@
5151
- 🎬 **多媒体支持**：内置音频/视频播放器，支持 Tab 切换自动暂停/恢复播放，优化资源占用。
5252
- 🌍 **主题与国际化**：内置明亮/暗黑模式一键切换，支持多语言（i18n）动态切换。
5353
- 🎭 **Mock 数据模拟**：基于 Faker.js 和 MSW 的纯前端 Mock 方案，脱离后端独立开发。
54+
- 📦 **组件库发布**：支持将 `src/components` 独立打包为 NPM 库 (`@w.ui/wui-react`)，提供 ESM/UMD 格式，支持按需加载与类型提示。
5455

5556
---
5657

@@ -127,6 +128,13 @@ npm run dev
127128
- 🎭 **Mock 增强**：多角色切换与权限同步
128129
- 🧪 **E2E 测试**：Playwright 核心场景覆盖
129130
- 📚 **文档完善**：文档与示例持续更新
131+
- **📦 组件库独立打包**: 新增 `@w.ui/wui-react` 组件库构建流程，支持 Vite Library Mode 打包 ESM/UMD 格式。
132+
- **🚀 发布流程自动化**: 集成 `standard-version` 版本管理与 NPM 发布脚本，支持 Scoped Package 发布。
133+
- **🎨 组件重构与优化**:
134+
- `DescBox`: 样式重构，适配移动端与暗黑模式。
135+
- `RadioInput`: 交互优化，支持 Tooltip 提示与自定义样式。
136+
- `Exception`: 规范化导出结构，修复模块解析问题。
137+
- **🛠️ 构建配置升级**: 完善 `vite.config.lib.ts`，配置路径别名 (`@assets`, `@hooks` 等) 与外部依赖，确保构建产物纯净。
130138

131139
---
132140

‎docs/LIBRARY_PUBLISH_GUIDE.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# 组件库打包与发布指南
2+
3+
本文档详细说明了 `@w.ui/wui-react` 组件库的打包配置、开发规范及发布流程。
4+
5+
## 1. 项目配置
6+
7+
### 1.1 构建配置 (`vite.config.lib.ts`)
8+
9+
项目使用 Vite 的库模式 (Library Mode) 进行打包。核心配置如下：
10+
11+
- **入口文件**: `src/components/index.ts`
12+
- **输出目录**: `dist-lib`
13+
- **格式**: 生成 `es` (ESM) 和 `umd` 格式
14+
- **外部依赖**: `react`, `react-dom`, `antd`, `react-router-dom` 等被配置为 `external`，不会打包进库文件中，而是作为 `peerDependencies`。
15+
- **类型定义**: 使用 `vite-plugin-dts` 自动生成 TypeScript 类型定义文件 (`.d.ts`)。
16+
- **路径别名**: 配置了 `@stateless`, `@hooks`, `@utils`, `@assets` 等别名，确保构建时能正确解析。
17+
18+
### 1.2 Package.json 配置
19+
20+
关键字段说明：
21+
22+
```json
23+
{
24+
"name": "@w.ui/wui-react",
25+
"version": "2.0.0",
26+
"files": ["dist-lib"],
27+
"main": "./dist-lib/pro-react-components.umd.js",
28+
"module": "./dist-lib/pro-react-components.es.js",
29+
"types": "./dist-lib/index.d.ts",
30+
"exports": {
31+
".": {
32+
"types": "./dist-lib/index.d.ts",
33+
"import": "./dist-lib/pro-react-components.es.js",
34+
"require": "./dist-lib/pro-react-components.umd.js"
35+
},
36+
"./style.css": "./dist-lib/style.css"
37+
},
38+
"peerDependencies": {
39+
"antd": ">=6.0.0",
40+
"react": ">=19.0.0",
41+
"react-dom": ">=19.0.0"
42+
},
43+
"scripts": {
44+
"build:lib": "vite build -c vite.config.lib.ts",
45+
"prepublishOnly": "npm run build:lib",
46+
"pub": "npm publish --access public",
47+
"pub:beta": "npm publish --tag beta --access public"
48+
}
49+
}
50+
```
51+
52+
## 2. 开发规范
53+
54+
### 2.1 组件开发
55+
- **目录结构**:
56+
- `src/components/stateless/`: 无状态组件（UI 组件）
57+
- `src/components/stateful/`: 有状态组件（业务组件）
58+
- `src/components/hooks/`: 自定义 Hooks
59+
- **样式**: 使用 Less Modules (`.module.less`) 避免样式冲突。
60+
- **资源引用**: 图片、视频等资源应放在 `src/assets` 下，并使用别名 `@assets` 引用。
61+
62+
### 2.2 导出组件
63+
所有需要发布的组件必须在 `src/components/index.ts` 中导出：
64+
65+
```typescript
66+
export { default as MyComponent } from './stateless/MyComponent';
67+
// 或者命名导出
68+
export { MyComponent } from './stateless/MyComponent';
69+
```
70+
71+
## 3. 构建流程
72+
73+
在发布之前，必须先进行构建以生成 `dist-lib` 目录。
74+
75+
```bash
76+
# 执行构建
77+
npm run build:lib
78+
```
79+
80+
构建产物包括：
81+
- `pro-react-components.es.js`: ESM 格式（用于现代构建工具）
82+
- `pro-react-components.umd.js`: UMD 格式（用于浏览器直接引入）
83+
- `style.css`: 所有组件的样式汇总
84+
- `index.d.ts`: 类型定义文件
85+
86+
## 4. 发布流程
87+
88+
### 4.1 准备工作
89+
1. 确保代码已提交并推送到远程仓库。
90+
2. 登录 NPM 账号：
91+
```bash
92+
npm login
93+
```
94+
95+
### 4.2 版本管理
96+
使用 `standard-version` 自动更新版本号并生成 CHANGELOG：
97+
98+
```bash
99+
# 发布标准版本 (自动判断版本升级类型)
100+
npm run release
101+
102+
# 手动指定版本升级
103+
npm run release:minor # 1.0.0 -> 1.1.0
104+
npm run release:patch # 1.0.0 -> 1.0.1
105+
npm run release:major # 1.0.0 -> 2.0.0
106+
```
107+
108+
### 4.3 发布到 NPM
109+
110+
```bash
111+
# 发布正式版
112+
npm run pub
113+
114+
# 发布 Beta 版
115+
npm run pub:beta
116+
```
117+
118+
> **注意**: 由于包名为 `@w.ui/wui-react` (Scoped Package)，发布时必须指定 `--access public`（脚本中已配置）。
119+
120+
## 5. 常见问题排查
121+
122+
1. **构建报错 "Cannot find module"**:
123+
- 检查 `vite.config.lib.ts` 中的 `alias` 配置是否包含该路径。
124+
- 检查 `tsconfig.json` 中的 `paths` 配置。
125+
- 确保文件扩展名正确（JSX 文件应为 `.jsx` 或 `.tsx`）。
126+
127+
2. **发布失败 "You do not have permission to publish"**:
128+
- 检查是否登录了正确的 NPM 账号。
129+
- 确认是否有 `@w.ui` 组织的发布权限。
130+
- 如果是个人项目，考虑更改包名为 `@your-username/wui-react`。
131+
132+
3. **样式丢失**:
133+
- 确保在使用库的项目中引入了样式文件：`import '@w.ui/wui-react/style.css';`
134+

0 commit comments

Comments
 (0)