workspaces(工作区)是一个通用术语,它指的是从单个顶级根包中管理本地文件系统中的多个包。
npm、yarn、pnpm都提供了对workspaces的支持,在使用上会有些微的不同,今天就分享一下这几个包管理器分别使用workspaces的方式
前段时间写几个独立的组件,当时因为没考虑要做成啥样,就把demo文档和组件放在一个包管理了,随着需求的增多,不得不把文档抽离出来,由于前期都是用的npm(因为要使用新发布的包),就直接使用npm的workspaces了
npm的workspaces介绍及使用
以一个简单的组件库demo为例
项目初始化
创建vangle目录为项目的根目录,初始化package.json
cd vangle
npm init -y
package.json
{
"name": "vangle",
"version": "1.0.0",
"license": "ISC"
}
手动添加子包
创建packages存放所有的子包,然后在该目录下新建docs和components目录,分别初始化子包的package.json
packages/components/package.json
{
"name": "components",
"version": "1.0.0",
"license": "ISC"
}
packages/docs/package.json
{
"name": "docs",
"version": "1.0.0",
"license": "ISC"
}
- 目录结构为
|-- vangle
|-- package.json
|-- packages
|-- components
| |-- package.json
|-- docs
|-- package.json
在根项目的package.json中添加workspaces,其实就是包的路径数组,支持Glob通配符,这里的路径指向指的是package.json所在文件夹文件夹名。
{
"name": "vangle",
"version": "1.0.0",
"license": "ISC",
"workspaces": [
"packages/components",
"packages/docs"
]
}
这时执行npm install后node_modules下就会有components和docs的依赖了
上面是手动添加子包的方式,npm也提供了命令行的方式添加,所做的功能和上面手动类似,-w
就是 --workspace
的简写,但用法稍有区别,如下:
npm init -w ./packages/a -y
# or
npm init --workspace=./packages/b -y
没有层级目录会自动创建,生成pckage.json并在根目录package.json中添加workspace路径
- workspaces也支持glob通配符,例如像下面这样配置表示匹配packages目录下所有的一级子包
{
"workspaces": [
"packages/*"
]
}
为子包添加、移除、更新依赖
- 如果想为components包添加dayjs依赖,可以使用一下命令操作,使用
-w [packageName]
来告诉npm为哪个子包添加依赖
npm install dayjs -w components
npm uninstall dayjs -w components
npm update dayjs -w components
# or
npm install dayjs --workspace=components
注意:如果在项目根目录运行
npm install
会同时将子包及子包的依赖一起安装到根node_modules下
使用子包
为components、docs分别添加如下代码,由于docs依赖components建议位docs包添加依赖
npm install components -w docs
// packages/components/index.js
export const button = 'button'
// packages/docs/index.js
import { button } from 'components'
console.log(button)
在docs/package.json中添加启动脚本
{
"name": "docs",
"version": "1.0.0",
"type": "module",
"main": "index.js",
"license": "ISC",
"scripts": {
"dev": "node index.js"
}
}
因为使用了ES module 需要添加"type": "module"
,在docs/index.js中导入了components,默认回去加载components/index.js,建议加上"main": "index.js"
,不然会有提示
- 运行启动命令 dev
npm run dev -w docs
# run many
npm run dev -w docs -w components
# or
npm run dev --workspace=docs
npm run test --workspace=docs --workspace=components
- 如果我们想启动子包的所有dev脚本可以使用
--workspaces
参数,如果有的子包没有dev脚本会报错,使用--if-present
参数可以避免
npm run dev --workspaces
# 有就运行
npm run dev --workspaces --if-present
在根package.json中运行工作区脚本
和上面一模一样,好处是可以简写运行的命令
"scripts": {
"dev": "npm run dev --workspaces",
"docs:dev": "npm run dev -w docs"
}
上面就是npm工作区的基本使用,这里快速总结一下几个常用命令
# 新增子包
npm init -w ./packages/a -y
# 为子包添加依赖
npm install dayjs -w components
# 运行子包的dev脚本
npm run dev -w docs
# 运行所有子包dev脚本,注意 --if-present 的使用时机
npm run dev --workspaces
yarn 使用 workspaces
其实和npm差不多,这里还是按上面的方式操作一遍
工作区是一种设置包架构的新方法,从 Yarn 1.0 开始默认可用。 它允许你设置多个包,这样你只需要运行 yarn install 就可以一次性安装所有包。
使用npm安装yarn
npm install -g yarn
项目初始化
创建vangle目录为项目的根目录,初始化package.json
cd vangle
yarn init -y
package.json
{
"name": "vangle",
"version": "1.0.0",
"main": "index.js",
"license": "MIT",
"private": true,
"workspace": [
"packages/docs",
"packages/components"
]
}
private:根目录一般是项目的脚手架,无需发布,"private": true会确保根目录不被发布出去
workspaces:其实就是包的路径数组,支持Glob通配符,这里的路径指向指的是package.json所在文件夹文件夹名。
相关命令
显示你当前项目的工作空间依赖树
yarn workspaces info
{
"docs": {
"location": "packages/docs",
"workspaceDependencies": [],
"mismatchedWorkspaceDependencies": []
},
"components": {
"location": "packages/components",
"workspaceDependencies": [],
"mismatchedWorkspaceDependencies": []
}
}
选定的工作空间(即包)中运行所选的yarn命令 yarn workspace <package-name> <command>
# 添加依赖
yarn workspace docs add dayjs
# 移除依赖
yarn workspace docs remove dayjs
如果你想为所有的包添加一个共同的依赖关系,进入项目的根目录并使用-W (或-ignore-workspace-root-check) 标志
yarn add dayjs -W -D
在docs包中安装components包(安装本地包),运行下面的命令,必须加上版本号
yarn workspace docs add components@1.0.0
# or
cd .\packages\docs
yarn add components@1.0.0
注意:如果远程仓库有相同名称相同版本的包会优先下载远程的,注意命名
hoist 依赖提升问题
如果我们直接切换到子包如:cd .\packages\docs
,然后添加依赖 yarn add -D typescript
,这时依赖还是会添加到根级的node_modules里
这是因为yarn默认会把子包安装的依赖会提升到根级,如果你想在子包中安装它,需要在根package.json中设置不需要提升的包nohoist
,注意workspaces的结构
{
"workspaces": {
"packages": [
"packages/*"
],
"nohoist": ["**/docs", "**/docs/**"]
}
}
npm 原始好像没有nohoist的实现,所以上面没讲 github.com/npm/rfcs/is…
运行工作区npm脚本
- 运行docs的dev脚本
yarn workspace docs dev
- 在根package.json中运行工作区脚本
yarn docs:dev
"scripts": {
"docs:dev": "yarn workspace docs dev"
}
pnpm 使用 workspaces
相比于npm和yarn,pnpm就是专门为menorepo而生的,提供了一些高级的workspaces用法。一些知名的开源项目如:Next.js、Vue3.0、Vite、Nuxt等都陆续使用pnpm作为脚手架。
使用pnpm有以下几个优势,这也是pnpm项目的初衷。
- 节省磁盘空间
- 提高安装速度
- 创建一个非扁平的 node_modules 目录
使用npm安装pnpm
npm install -g pnpm
pnpm和npm、yarn的用法相似,这里就不作过多介绍了,主要讲讲与workspaces
相关的内容
项目初始化
创建vangle目录为项目的根目录,初始化package.json
mkdir vangle
cd vangle
pnpm init -y
pnpm 内置了对单一存储库(也称为多包存储库、多项目存储库或单体存储库)的支持, 你可以创建一个 workspace 以将多个项目合并到一个仓库中。
与npm、yarn不同,pnpm的workspaces的配置都放在pnpm-workspace.yaml文件里
一个 workspace 的根目录下必须有 pnpm-workspace.yaml 文件, 也可能会有 .npmrc 文件。
pnpm-workspace.yaml 定义了 工作空间 的根目录,并能够使您从工作空间中包含 / 排除目录 。 默认情况下,包含所有子目录。
# pnpm-workspace.yaml
packages:
# all packages in direct subdirs of packages/
- 'packages/*'
# # all packages in subdirs of components/
# - 'components/**'
# # exclude packages that are inside test directories
# - '!**/test/**'
初始化子包命令
和 npm 类似
pnpm init -w ./packages/docs -y
pnpm init -w ./packages/components -y
- 在项目根目录安装依赖
# 使用 --ignore-workspace-root-check 或 -w 来标记,否则在 root workspace 包添加依赖项时会失败。
pnpm add dayjs -w
- 为子包添加依赖,
--filter
或-F
的使用,--filter 后面跟的是包名
pnpm add dayjs --filter docs
- 安装工作区里的子包,例如docs安装components作为依赖
pnpm add components --filter docs
我们看看docs/package.json中写入的是什么"components": "workspace:^1.0.0"
,前面有workspace:
说明这个依赖来自于本地工作区
{
"dependencies": {
"components": "workspace:^1.0.0",
"dayjs": "^1.11.7"
}
}
workspace:
是pnpm Workspace的协议,这里是官网的详细解释
默认情况下,如果可用的 packages 与已声明的可用范围相匹配,pnpm 将从工作区链接这些 packages。 例如, 如果bar引用"foo": "^1.0.0"
并且foo@1.0.0
存在工作区,那么pnpm会从工作区将foo@1.0.0
链接到bar。 但是,如果 bar 的依赖项中有 "foo": "2.0.0"
,而 foo@2.0.0
在工作空间中并不存在,则将从 npm registry 安装 foo@2.0.0
。 这种行为带来了一些不确定性。
幸运的是,pnpm 支持 workspace 协议 workspace:
。 当使用此协议时,pnpm 将拒绝解析除本地 workspace 包含的 package 之外的任何内容。 因此,如果您设置为 "foo": "workspace:2.0.0"
时,安装将会失败,因为 "foo@2.0.0"
不存在于此 workspace 中。
当 link-workspace-packages 选项被设置为 false 时,这个协议将特别有用。 在这种情况下,仅当使用 workspace: 协议声明依赖,pnpm 才会从此 workspace 链接所需的包。
详细内容请参考 pnpm.io/zh/workspac…
hoist相关配置
pnpm 提升方式,我们可以在 .npmrc
对其进行配置,.npmrc
文件都遵循 INI-formatted 列表,包含 key = value 参数。
更详细的配置请参考 pnpm.io/zh/npmrc
hoist
- 默认值: true
- 类型: boolean
当 hoist 为 true 时,所有依赖项都会被提升到 node_modules/.pnpm/node_modules。 这使得 node_modules所有包都可以访问 未列出的依赖项。
hoist = true
hoist-pattern
- 默认值: ['*']
- 类型: string[]
告诉 pnpm 哪些包应该被提升到 node_modules/.pnpm/node_modules。 默认情况下,所有包都被提升 —— 但是,如果您知道只有某些有缺陷的包具有幻影依赖,您可以使用此选项专门提升幻影依赖(推荐做法)。
例如:
hoist-pattern[]=*eslint*
hoist-pattern[]=*babel*
还可以使用排除模式,过滤不需要提升的依赖
例如:
hoist-pattern[]=*types*
hoist-pattern[]=!@types/react
shamefully-hoist
- 默认值: false
- 类型:Boolean
默认情况下,pnpm 创建一个半严格的 node_modules,这意味着依赖项可以访问未声明的依赖项,但 node_modules 之外的模块不行。 通过这种布局,生态系统中的大多数的包都可以正常工作。 但是,如果某些工具仅在提升的依赖项位于根目录的 node_modules 时才有效,您可以将其设置为 true 来为您提升它们。
shamefully-hoist = true
运行工作区npm脚本
- 运行docs的dev脚本
pnpm --filter docs dev
- 在根package.json中运行工作区脚本
pnpm docs:dev
"scripts": {
"docs:dev": "pnpm --filter docs dev"
}
最后
本文介绍了在npm、yarn、pnpm中使用workspaces的方式,基本功能都有实现,但pnpm确实提供了npm和yarn所没有的功能,可以根据项目的需要具体选择使用哪个