董海洋
160 lines
4.5 KiB
Markdown
160 lines
4.5 KiB
Markdown
# monorepo-template
|
|
|
|
## 分包、分仓原则
|
|
|
|
### 分仓
|
|
|
|
- 原则上，将关联性强的库放在同一monorepo仓库下，便于调试、开发以及版本管理
|
|
- 关联性不强，仅引用某个包的库不建议都放在同一仓库中，可能带来管理上的负担
|
|
|
|
### 分包
|
|
|
|
- 不同目的、功能应分在不同包中
|
|
- 想要进行单独的版本控制、构建、发布等，应分在不同包中
|
|
|
|
## monorepo目录
|
|
|
|
```bash
|
|
.
|
|
├── .husky # git钩子
|
|
├── .vscode # vscode配置
|
|
├── docs # 文档目录
|
|
├── packages # 存放组件包
|
|
│ ├── xxxx # 组件包1
|
|
│ └── xxxx # 组件包2
|
|
├── play # 调试目录
|
|
├── eslint.config.ts # eslint配置
|
|
├── commitlint.config.js # commitlint配置
|
|
├── unoconfig.ts # unocss配置
|
|
├── package.json # 项目配置
|
|
├── .npmrc # npm配置
|
|
├── .nvmrc # nvm配置
|
|
├── pnpm-workspace.yaml # pnpm workspace配置
|
|
├── vitest.workspace.ts # vitest workspace配置
|
|
├── README.mdx # 生成文档时的描述文件
|
|
└── READM.md # 项目自述
|
|
|
|
```
|
|
|
|
## 命名规范
|
|
|
|
- 项目以`fe-xxx`开头
|
|
- npm包应统一放在`@lingshu`的命名空间下，包名全称应为`@lingshu/xxx`
|
|
- 内部通用组件以ls开头，例如`<ls-contacts-select>`
|
|
|
|
## 新建npm包
|
|
|
|
### 复用模板
|
|
|
|
拷贝复制demo1-components文件夹
|
|
|
|
### 修改
|
|
|
|
- 修改文件夹名（推荐以包名为文件夹名）
|
|
- 修改`packages.json`文件
|
|
- `name`
|
|
- `version`
|
|
- 修改`README.md`文件
|
|
- 根据需要修改src中文件进行开发
|
|
|
|
### 添加调试与文档
|
|
|
|
> 具体看下方`调试`,`文档`
|
|
|
|
## 调试
|
|
|
|
调试统一通过play文件夹下的playground进行调试
|
|
为调试子包中的内容，需要按以下步骤
|
|
|
|
1. 在play文件夹下的package.json中添加子包为依赖，版本为"workspace:\*”
|
|
2. 根目录下运行命令
|
|
|
|
```bash
|
|
pnpm dev
|
|
```
|
|
|
|
3. 根据子包的使用方式，修改playground中src中代码，引用子包
|
|
4. 修改子包代码可以通过热更新实时生效
|
|
|
|
> 为保证调试正常，子包入口文件需强制为src/index，模板默认已配好，若无必要请勿改动
|
|
>
|
|
> playground中将所有子包的`@`指向为对应包的`src`目录
|
|
|
|
### mock
|
|
|
|
调试mock统一写在play文件夹下的mock文件夹下
|
|
|
|
mock启动指令
|
|
|
|
```bash
|
|
pnpm dev:mock
|
|
```
|
|
|
|
## 文档生成
|
|
|
|
基于[storybook](https://storybook.js.org/docs)
|
|
|
|
### 文档相关目录
|
|
|
|
```bash
|
|
.
|
|
├── docs # 文档目录
|
|
│ └── .storybook # 组件包2
|
|
│ ├── main.ts # 文档配置
|
|
│ ├── manager.ts # 文档管理
|
|
│ ├── preview.ts # 文档预览配置，有关样式和组件在此引入
|
|
│ └── theme.ts # 文档主题
|
|
├── packages
|
|
│ ├── xxxx # 组件包1
|
|
│ │ ├── Introduction.mdx # 包描述文档
|
|
│ │ └── src
|
|
│ │ └── **
|
|
│ │ └── *.stories.ts # 组件文档
|
|
│ └── xxxx # 组件包2
|
|
└── READM.mdx # 仓库总描述文档
|
|
|
|
```
|
|
|
|
### 文档编写
|
|
|
|
参考[storybook文档](https://storybook.js.org/docs/get-started/frameworks/vue3-vite)
|
|
|
|
> 若组件库中有使用其他npm包，在app中注册，则需要在`docs/.storybook/preview.ts`中以相同方式注册，如`element-plus`
|
|
|
|
```typescript
|
|
// docs/.storybook/preview.ts
|
|
import ElementPlus from 'element-plus-cisdi';
|
|
import 'element-plus-cisdi/dist/index.css';
|
|
|
|
setup((app) => {
|
|
app.use(ElementPlus);
|
|
});
|
|
```
|
|
|
|
#### 库说明文档
|
|
|
|
写在组件包根目录下的Introduction.mdx中,支持markdown语法和javascript语法，具体可看[storybook/MDX](https://storybook.js.org/docs/writing-docs/mdx)
|
|
|
|
#### 组件文档
|
|
|
|
1.在组件同级新建`.stories.ts`文件，并确保能被 文档配置的`main.ts`中的`stories`路径匹配`.stories.ts`文件可参考模板中文件，其中`title` 应以包名为前缀，如
|
|
|
|
```typescript
|
|
{
|
|
title: 'demo1-components/lingshuPlainText';
|
|
}
|
|
```
|
|
|
|
2.在组件中以JSDOC 标签写注释，支持props、emit、slot、expose
|
|
|
|
#### 指令
|
|
|
|
根目录下运行
|
|
|
|
```bash
|
|
pnpm storybook #预览生成的文档
|
|
pnpm build:storybook #打包构建文档
|
|
```
|
|
|
|
打包的文档在`docs/storybook-static`目录下
|