快速使用 pnpm 配置 monorepo

一、创建 pnpm-workspace.yaml

pnpm-workspace.yaml 用于管理 monorepo 中项目目录。

例如：

packages:
  # all packages in direct subdirs of packages/
  - "packages/*"
  # all apps in subdirs of components/
  - "apps/*"

二、项目初始化

使用 pnpm init 初始化每个项目，如果是 pnpm 或 npm 命令创建的项目会自动包含 package.json 。

my-monorepo/
├── pnpm-workspace.yaml
├── packages/
│   └── tailwindcss/
│       ├── index.js
│       └── package.json
├── apps/
│   ├── app1/
│   │   ├── index.js
│   │   └── package.json
│   └── app2/
│       ├── index.js
│       └── package.json
└── package.json

三、项目间安装依赖

在项目间引用项目，需要进入到指定项目目录，然后执行 install ，例如：

pnpm i [要安装到项目名，在项目的package.json中查看]@workspace:*

# 注意如果抛出错误 no matches found，那么可能是终端需要输入字符串格式项目名，例如：
# pnpm i @app/practice@workspace:*
# @workspace:* 表示安装项目的最新版本

四、工作空间全局安装依赖

工作空间内安装依赖时，只需执行

pnpm i [package-name] -D or -S -w
# -D or -S 表示安装依赖为 dependencies 还时 devDependencies
# -w 表示安装到工作空间

五、关联工作区的包链接

注意：必须安装公共包才能在各项目间建立正确依赖。

在 monorepo 的根目录下运行 pnpm install 以确保所有工作区的包都被正确链接。

六、将子项目依赖安装到workspace

当我们在 monorepo 根路径执行 pnpm install 时，就会自动将子项目依赖安装到 monorepo 根路径的node_modules 中。

谨记，pnpm i [package-name] -w 。

六、示例及错误处理

例如，我们创建一个tailwindcss配置项目，如果你在尝试使用 pnpm add @react/tailwindcss@workspace:* 时遇到 "no matches found" 错误，可能是因为以下原因：

包名错误：确保你使用的包名是正确的，检查每个项目下 package.json 文件中的 name 。
包未被发布到 workspace：确保包正确地包含在 pnpm-workspace.yaml 文件中。
工作区未正确配置：确保你的工作区配置正确并且 pnpm 可以正确识别它们。

以下是详细的检查和解决步骤：

1. 检查包名和目录结构

确保你的包名和目录结构正确。例如，如果你有一个 @react/tailwindcss 包，它应该有一个有效的 package.json 文件和相应的目录结构。

{
  "name": "@app/test", 
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@app/practice": "workspace:^"
  }
}

其中，name 即为项目名，可以自定义，但是在别的项目中安装该项目时，必须使用该package.json 中正确的 name 。

2. 配置 pnpm-workspace.yaml

确保 pnpm-workspace.yaml 文件正确配置，并且包含了所有相关的包路径。

pnpm-workspace.yaml:

packages:
  - 'packages/*'
  - 'apps/*'

3. 检查 package.json 文件

确保你的 @react/tailwindcss 包的 package.json 文件正确设置了 name 字段。

packages/tailwindcss/package.json:

{
  "name": "@react/tailwindcss",
  "version": "1.0.0",
  "main": "index.js"
}

七、注意事项

安装公共包

在 monorepo 的根目录下运行 pnpm install 以确保所有工作区的包都被正确链接。

pnpm install

这一步很重要，如果不执行安装，那么各项目间无法正确建立 node_modules 依赖关系。

详见官方说明文档，如下：

基于符号链接的 node_modules 结构 | pnpm

正确的 node_modules 依赖关系

node_modules
└── .pnpm
    ├── bar@1.0.0
    │   └── node_modules
    │       └── bar -> <store>/bar
    │           ├── index.js
    │           └── package.json
    └── foo@1.0.0
        └── node_modules
            └── foo -> <store>/foo
                ├── index.js
                └── package.json

在应用中添加公共包

在你的应用中安装 @react/tailwindcss 包。

cd apps/app1
pnpm add @react/tailwindcss@workspace:*

如果你仍然遇到 "no matches found" 错误，可以尝试以下步骤：

使用引号包围依赖项

某些 shell 环境可能需要使用引号来包围依赖项字符串，以避免 shell 解析错误。

pnpm add "@react/tailwindcss@workspace:*"

清理缓存和重新安装

有时，清理 pnpm 缓存和重新安装依赖可能会解决问题。

pnpm store prune
pnpm install

示例项目结构

确保你的项目结构如下：

my-monorepo/
├── pnpm-workspace.yaml
├── packages/
│   └── tailwindcss/
│       ├── index.js
│       └── package.json
├── apps/
│   ├── app1/
│   │   ├── index.js
│   │   └── package.json
│   └── app2/
│       ├── index.js
│       └── package.json
└── package.json

通过上述步骤，你应该能够在 pnpm 工作区中正确地共享和安装公共包。如果问题仍然存在，请确保所有文件和目录结构正确，并且所有路径和名称都匹配。

使用 pnpm 快速配置 monorepo