搭建vue3组件库(一): Monorepo架构搭建

文章目录

- [1. 以 pnpm 构建 monorepo](#1. 以 pnpm 构建 monorepo)
- - [1.1 全局安装 pnpm](#1.1 全局安装 pnpm)
  - [1.2 配置 pnpm 的 monorepo 工作区](#1.2 配置 pnpm 的 monorepo 工作区)
  - [1.3 仓库项目内的包相互调用](#1.3 仓库项目内的包相互调用)
  - [1.4 TypeScript 初始化配置文件](#1.4 TypeScript 初始化配置文件)
- [2. 通用配置文件](#2. 通用配置文件)
- - [2.1 添加 .editorconfig 编辑器格式配置文件](#2.1 添加 .editorconfig 编辑器格式配置文件)
  - [2.2 添加 .gitignore git 忽略文件](#2.2 添加 .gitignore git 忽略文件)
  - [2.3 添加 .npmrc npm配置文件](#2.3 添加 .npmrc npm配置文件)
  - [2.4 工作区配置](#2.4 工作区配置)
  - [2.5 添加 .gitattributes 配置git 使用的文件和路径的属性](#2.5 添加 .gitattributes 配置git 使用的文件和路径的属性)
- [3. play 项目搭建](#3. play 项目搭建)
- - [3.1 使用 Vite 来创建项目](#3.1 使用 Vite 来创建项目)
- [4. TypeScript 的 Monorepo 设置](#4. TypeScript 的 Monorepo 设置)
- - [4.1 TypeScript 项目引用](#4.1 TypeScript 项目引用)
  - [4.2 TypeScript 的类型检查](#4.2 TypeScript 的类型检查)
  - [4.3 串行/并行执行脚本](#4.3 串行/并行执行脚本)

1. 以 pnpm 构建 monorepo

monorepo 是一个项目仓库，里面可以存放多个项目，每个项目可以独立管理，并且可以共享依赖。

pnpm 全称 performant npm，意思为高性能的 npm。pnpm 由 npm/yarn 衍生而来，解决了 npm/yarn 内部潜在的 bug，极大的优化了性能，扩展了使用场景。

1.1 全局安装 pnpm

bash 复制代码

  npm install -g pnpm

然后在项目下使用 pnpm init 进行 package.json 的初始化,得到 package.json 初始内容，然后把 package.json 中的 name 属性删掉，并且添加一个 "private": true 属性，因为它是不需要发布的。

为了减少因node的版本的差异而产生开发环境错误，在package.json中增加engines字段来限制版本

为项目指定使用指定版本的node.js，在package.json中增加peerDependencies字段来限制版本

javascript 复制代码

  {
    "private": true,
    "scripts": {},
    "peerDependencies": {
      "vue": "^3.2.0"
    },
    "engines": {
      "node": ">=16"
    },
  }

1.2 配置 pnpm 的 monorepo 工作区

在这个仓库下，我们需要管理多个项目，就可以采用 pnpm 的 monorepo。在仓库的根目录下创建一个 pnpm-workspace.yaml 文件，可以在 pnpm-workspace.yaml 配置文件中指定这个仓库中有多少个项目。

yaml 复制代码

packages:
  - packages/*
  - docs
  - play
  - internal/*

play 目录是示例项目，在开发的时候可以知道效果是否达到预期；

docs 目录是文档项目，展示组件的使用方法；

internal 目录是内部项目，存放一些私有组件，比如：打包方法、等；

packages 目录是所有组件的项目目录了，在 packages 目录中又可以放很多包的项目目录，比如，组件包目录：components 、主题包目录：theme-chalk 、工具包目录：utils 等。

然后每一个包目录里面也需要一个 package.json 文件进行声明这是一个 NPM 包目录。所以需要进入每个包目录进行初始一个 package.json 文件。

以 components 包为例，进入到 components 目录底下初始化一个 package.json 文件，更改包名：@vision-ui-vue/components。文件内容如下：

javascript 复制代码

{
  "name": "@vision-ui-vue/components",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

其他两个的包名则分别为：@vision-ui-vue/theme-chalk 和 @vision-ui-vue/utils，创建过程同上。

至此一个初步搭建的项目目录结构如下：

javascript 复制代码

├── docs
├── packages
│   ├── components
│   │   └── package.json
│   ├── theme-chalk
│   │   └── package.json
│   └── utils
│       └── package.json
├── play
├── package.json
└── pnpm-workspace.yaml

1.3 仓库项目内的包相互调用

@vision-ui-vue/components 、@vision-ui-vue/theme-chalk 、@vision-ui-vue/utils 这几个包要互相进行调用呢，就需要把它们安装到仓库根目录下的 node_modules 目录中。

在根目录下进行安装操作

bash 复制代码

pnpm install @vision-ui-vue/components -w
pnpm install @vision-ui-vue/theme-chalk -w
pnpm install @vision-ui-vue/utils -w

-w 表示安装到共公模块的 packages.json 中，也就是根目录下的 packages.json

安装后根目录下的 package.json 的内容为：

json 复制代码

{
  "dependencies": {
    "@vision-ui-vue/components": "workspace:^",
    "@vision-ui-vue/theme-chalk": "workspace:^",
    "@vision-ui-vue/utils": "workspace:^"
  }
}

workspace:^ 将来发布的时候会被转换成具体的版本号。

1.4 TypeScript 初始化配置文件

安装依赖

bash 复制代码

pnpm install vue typescript @types/node -D -w

安装完成后，执行 pnpm tsc --init 初始化TypeScript配置文件tsconfig.json。

2. 通用配置文件

2.1 添加 .editorconfig 编辑器格式配置文件

在根目录新建 .editorconfig 文件，内容如下

bash 复制代码

# 此文件为 EditorConfig 配置文件，用于设置通用的代码格式化规则。
# root = true 表明此配置文件是根配置，对整个项目生效。
root = true

# 此段配置适用于所有文件类型
[*]
# 字符编码设置为 UTF-8
charset = utf-8
# 使用空格进行缩进，而非制表符
indent_style = space
# 每个层级的缩进大小为 2 个空格
indent_size = 2
# 行尾换行符使用 LF (Unix) 格式
end_of_line = lf
# 在文件末尾自动添加新行
insert_final_newline = true
# 自动删除行尾的多余空格
trim_trailing_whitespace = true
# 引用字符串默认使用单引号
quote_type = single

2.2 添加 .gitignore git 忽略文件

在根目录新建 .gitignore 文件，内容如下

bash 复制代码

# 此文件用于指定在项目中应当被忽略的文件和文件夹
# 忽略的项目主要分为以下几类：

# 编辑器目录和文件
.idea

# 包管理器相关文件
node_modules
.pnpm-debug.log*

# 系统产生的文件
.DS_Store

# 打包输出的目录和文件
dist
coverage
packages/vision-ui-vue/version.ts

# 本地环境配置文件
*.local
.eslintcache
# Cypress 测试产生的文件
cypress/screenshots/*
cypress/videos/*
# 临时文件
tmp

2.3 添加 .npmrc npm配置文件

在根目录新建 .npmrc 文件，内容如下

bash 复制代码

# shamefully-hoist=true: 允许在npm安装时跨范围提升依赖，这可能会导致某些依赖版本的不一致。
shamefully-hoist=true

# strict-peer-dependencies=false: 关闭对peer dependencies的严格检查，这意味着在安装时即使peer dependencies不匹配也不会报错。
strict-peer-dependencies=false

# shell-emulator=true: 启用shell模拟器，这可能在某些环境下用于模拟终端行为，例如在没有真实终端的环境中运行shell命令。
shell-emulator=true

2.4 工作区配置

在根目录新建 .vscode 文件夹
在 .vscode 文件夹下新建 settings.json 文件，用来配置vscode编辑器和相关插件

json 复制代码

{
  "editor.formatOnSave": true,
  "npm.packageManager": "pnpm",
  "eslint.probe": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "html",
    "vue",
    "markdown",
    "json",
    "jsonc"
  ],
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "html",
    "vue",
    "markdown",
    "json",
    "jsonc"
  ],
  "i18n-ally.localesPaths": "packages/locale/lang"
}

在 .vscode 文件夹下新建 extensions.json 文件，推荐当前项目使用的插件

json 复制代码

{
  "recommendations": [
    "vue.volar",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "antfu.vite",
    "lokalise.i18n-ally"
  ]
}

2.5 添加 .gitattributes 配置git 使用的文件和路径的属性

在根目录下新建 .gitattributes 文件，内容如下

bash 复制代码

#
# 此文件用于配置不同文件类型的属性，主要关注于语言检测设置。
# 文件使用键值对的形式，其中键表示文件扩展名，值则为该文件类型的属性设置。
# 属性设置可以包含多个指令，用等号分隔。这里的指令主要关注于"linguist-detectable"，
# 用于告诉GitHub的Linguist库是否应检测和统计特定文件类型。
#

# 配置所有文本文件默认的行尾字符为LF
text=auto eol=lf

# 接下来，对于特定的文件类型，设置其是否被Linguist库检测。
# 对于CSS、SCSS和TS文件，这里设置为不进行检测。
*.ts linguist-detectable=false
*.css linguist-detectable=false
*.scss linguist-detectable=false

# 对于JS和Vue文件，设置为允许Linguist库进行检测。
*.js linguist-detectable=true
*.vue linguist-detectable=true

3. play 项目搭建

3.1 使用 Vite 来创建项目

bash 复制代码

pnpm create vite play --template vue-ts

在根目录执行 pnpm install 安装依赖，进入 play 目录执行 pnpm dev 启动项目。但是每次这样执行太麻烦了，可以在根目录的 package.json 文件的 scripts 选项进行以下配置：

javascript 复制代码

{
"scripts": {
    "dev": "pnpm -C play dev"
  }
}

这样就可以在根目录通过 pnpm run dev 启动 play 项目里面 package.json 文件中 scripts 选项中对应的 dev 命令了。

4. TypeScript 的 Monorepo 设置

上面通过 pnpm 提供的通过构建 pnpm-workspace.yaml 文件，进行声明对应的工作区的方式构建整个项目的结构。这种方式主要是以功能模块进行划分目录结构的，比如说，一个功能包目录里面包含了测试模块，但在最终进行生产编译打包的时候，不希望对测试模块的文件进行打包的，所以需要在 TypeScript 编译进行划分模块，让生产的时候只进行核心模块进行编译打包。

4.1 TypeScript 项目引用

tsconfig.json 文件有一个顶级属性references ，它支持将 TypeScript 的程序项目分割成更小的组成部分，进而可以提高类型检查和编译的速度。组件库已经采取 monorepo 的方式进行管理，也就是将项目根据功能的不同拆分成多个子项目，原则上各子项目之间尽量减少耦合度。比如说上面初步把组件库分成组件部分（packages）和展示部分（play），还有将来的测试部分（tests），测试和展示部分都是依赖组件部分的，但测试和展示部分是没有关联，所以测试或展示任何一部分发生了改变，应该只编译发生改变的部分，另外没有发生变化的部分不应该进行编译才对。

那么通过 tsconfig.json 文件的顶级属性references，就可以将组件库再进行划分，从而变得更加的合理和编译性能的进一步提升。

上面 1.3 步，已经在根目录初始化了tsconfig.json 文件，修改内容如下：

json 复制代码

{
  "files": [],
  "references": [
    { "path": "./tsconfig.web.json" }, // 组件包部分
    { "path": "./tsconfig.play.json" } // 组件 play 部分
  ]
}

每个引用的 path 属性可以指向包含 tsconfig.json 文件的目录，也可以指向配置文件本身。经过上面的设置，就等于是在 TypeScript 层又把组件库项目分成了三个部分。然后通过具体配置文件进行具体每个部分的 TypeScript 编译项设置。而每个部分都有一些公共的配置项，所以又可以把公共的配置项进行抽离设置到一个公众配置文件中，再通过 extends 进行引用，这样一来就可以大大减少相同的配置代码。

组件包部分配置项 tsconfig.web.json 文件：

json 复制代码

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "composite": true, // 是否开启项目编译，开启该功能，将会生成被编译文件所在的目录，同时开启declaration、declarationMap和incremental，默认：false
    "jsx": "preserve", // 指定JSX代码生成用于的开发环境
    "lib": ["ES2018", "DOM", "DOM.Iterable"], // 指定项目运行时使用的库
    "types": ["unplugin-vue-define-options"], // 用来指定需要包含的模块，并将其包含在全局范围内
    "skipLibCheck": true // 是否跳过声明文件的类型检查，这可以在编译期间以牺牲类型系统准确性为代价来节省时间，默认：false
  },
  "include": ["packages",],// 使用 include 来指定应从绝对类型中使用哪些类型
  "exclude": [ // 提供用于禁用 JavaScript 项目中某个模块的类型获取的配置
    "node_modules",
    "**/dist",
    "**/__tests__/**/*",
    "**/gulpfile.ts",
    "**/test-helper",
    "packages/test-utils",
    "**/*.md"
  ]
}

通过 include 属性进行限制组件部分的范围

组件 play 部分配置项 tsconfig.play.json 文件：

json 复制代码

{
  "extends": "./tsconfig.web.json",
  "compilerOptions": {
    "allowJs": true, // 是否允许编译器编译JS，JSX文件
    "lib": ["ESNext", "DOM", "DOM.Iterable"] // 指定项目运行时使用的库
  },
  "include": [ // 使用 include 来指定应从绝对类型中使用哪些类型
    "packages",
    "typings/components.d.ts",
    "typings/env.d.ts",
    "play/main.ts",
    "play/env.d.ts",
    "play/src/**/*"
  ]
}

通过 include 属性进行限制 play 部分的范围

公共配置项 tsconfig.base.json 文件：

json 复制代码

{
  "compilerOptions": {
    "outDir": "dist", // 指定输出目录
    "target": "es2018", // 目标语言的版本
    "module": "esnext", // 生成代码的模板标准
    "baseUrl": ".", // 解析非相对模块的基地址，默认是当前目录
    "sourceMap": false, // 是否生成相应的Map映射的文件，默认：false
    "moduleResolution": "node", // 指定模块解析策略，node或classic
    "allowJs": false, // 是否允许编译器编译JS，JSX文件
    "strict": true, // 是否启动所有严格检查的总开关，默认：false，启动后将开启所有的严格检查选项
    "noUnusedLocals": true, // 是否检查未使用的局部变量，默认：false
    "resolveJsonModule": true, // 是否解析 JSON 模块，默认：false
    "allowSyntheticDefaultImports": true, // 是否允许从没有默认导出的模块中默认导入，默认：false
    "esModuleInterop": true, // 是否通过为所有导入模块创建命名空间对象，允许CommonJS和ES模块之间的互操作性，开启改选项时，也自动开启allowSyntheticDefaultImports选项，默认：false
    "removeComments": false, // 删除注释
    "rootDir": ".", // 指定输出文件目录(用于输出)，用于控制输出目录结构
    "types": [],
    "paths": { // 路径映射，相对于baseUrl
      "@vision-ui-vue/*": ["packages/*"]
    }
  }
}

4.2 TypeScript 的类型检查

对于纯 TS 文件的项目，可以通过 tsc --noEmit 命令来进行类型检查，tsc --noEmit 的意思就是只进行 TypeScript 的语法检测，而不会进行编译。在调用 tsc 命令时可以使用命令行参数 --project （或 -p ）指定配置文件进行执行。

包含 SFC 单文件(.vue)组件的项目，我们则可以使用 Vue 官方提供的 vue-tsc 工具进行类型检查。

json 复制代码

{
  "scripts":{
   	"typecheck:web": "vue-tsc -p tsconfig.web.json --composite false --noEmit",
    "typecheck:play": "vue-tsc -p tsconfig.play.json --composite false --noEmit"
	}
}

--composite false 不进行增量编译，增量编译指的是生成 .d.ts 和 tsconfig.tsbuildinfo 文件，使用 vue-tsc 法语检查时不能设置为 true。

--noEmit 不进行编译，只进行语法检测。

--composite false --noEmit 不进行编译，也不进行增量编译，只进行语法检测。

--composite false 只能设置为 false，不能设置为 true。

4.3 串行/并行执行脚本

上面进行 TypeScript 类型检查的时候在 package.json 的 script 中配置了多个模块的命令，如果需要同时全部执行所有的命令，需要进行以下的设置：

json 复制代码

{
  "scripts":{
    "runall":"pnpm run typecheck:web && pnpm run typecheck:play"
  }
}

以上方式属于通过 && 符号来串行执行脚本。

如果需要并行执行脚本，可以使用 & 符号。

npm-run-all 是一个可并行或串行运行多个 npm-scripts 的 CLI 工具。

安装 npm-run-all 工具，安装命令为：

bash 复制代码

pnpm install npm-run-all -D -w

npm-run-all 提供三个命令，分别是 npm-run-all run-s run-p，后两个是 npm-run-all 带参数的简写，分别对应串行和并行。

有了这个包，就可以进行以下设置了：

json 复制代码

{
  "scripts":{
    "typecheck": "run-p typecheck:web typecheck:play"
  }
}

串行命令和并行命令执行规则：

一个 & 是代表并行执行左指令和右侧指令

两个 && 是代表串行执行，先执行左侧指令，再执行右侧命令

如果一个命令中既包含 & ,也包含 &&。&并行的级别要高一些，首先会执行&左右两侧的命令，然后再根据左右两侧指令情况进行执行。