# 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`目录下