如何在配置TS References的monorepo中正确配置Yarn 2 PnP？

1. 根目录基础配置 #

首先统一根侧PnP规则，禁用子目录独立PnP实例：

• 根目录package.json（序号1）开启workspace声明：

{
  "private": true,
  "workspaces": [
    "client",
    "global",
    "server"
  ],
  "packageManager": "yarn@3.6.4" // 替换为你当前使用的Yarn v3具体版本
}

• 根目录新增.yarnrc.yml配置：

nodeLinker: pnp
enableGlobalCache: false
pnpMode: strict
enableTransparentWorkspaces: true
# 禁止子目录生成独立的pnp.cjs文件
pnpEnableInheritance: true

删除client/、global/、server/目录下所有独立的.yarn文件夹、.pnp.cjs、.yarnrc.yml文件，全项目依赖统一由根目录PnP实例管控。

2. global共享包配置调整 #

2.1 package.json配置 #

修改global/package.json（序号5），明确包标识和导出规则：

{
  "name": "@your-project/global", // 自定义包名，后续client/server直接引用该名称
  "main": "./build/index.js",
  "types": "./build/index.d.ts",
  "dependencies": {
    // 保留原有firebase、draft-js等依赖声明
  }
}

2.2 tsconfig.json配置 #

修改global/tsconfig.json（序号6），适配PnP模块解析规则：

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es5",
    "lib": ["es2015", "dom"],
    "esModuleInterop": true,
    "declaration": true,
    "outDir": "./build",
    "rootDir": "./src",
    "strict": false,
    // 新增配置适配PnP解析
    "moduleResolution": "node16",
    "allowSyntheticDefaultImports": true
  },
  "include": ["src/**/*"],
  "exclude": ["build", "**/*.spec.ts"]
}

该配置直接解决构建global时找不到firebase依赖的问题：原TS配置的模块解析规则不兼容PnP缓存寻址逻辑，切换为node16解析规则后可直接读取根目录PnP挂载的依赖。

3. client与server依赖配置 #

不需要手动配置TS路径别名、portal/link协议，直接通过workspace协议关联本地global包：

• 给client添加依赖：执行yarn workspace client add @your-project/global@workspace:*
• 给server添加依赖：执行yarn workspace server add @your-project/global@workspace:*
workspace:*协议会自动关联本地global包的最新代码，无需手动同步版本。

4. 各项目TS配置调整 #

4.1 NextJS客户端配置 #

修改client/tsconfig.json（序号4）：移除原来@global/*的paths映射配置，直接通过import xxx from '@your-project/global'引用即可。
如果使用NextJS 12及以下版本，在next.config.js中添加PnP适配：

const PnpWebpackPlugin = require('pnp-webpack-plugin')
module.exports = {
  webpack: (config) => {
    config.resolve.plugins.push(PnpWebpackPlugin)
    config.module.rules.forEach(rule => {
      if (rule.use?.loader === 'next-babel-loader') {
        rule.use.options.plugins.push(PnpWebpackPlugin.babel)
      }
    })
    return config
  }
}

4.2 Express服务端配置 #

修改server/tsconfig.json（序号8）：

• 移除原来global/*的paths映射配置
• 移除exclude规则中的../global/**/*.ts
• compilerOptions新增"moduleResolution": "node16"
• 保留原有的references配置，tsc构建时会自动先构建依赖的global包
• 保留typescript-transform-paths插件配置，PnP会自动配合插件处理产物路径映射

该配置直接解决服务端无法解析依赖、找不到pnpapi的问题：所有子项目依赖统一走根目录PnP实例寻址，workspace协议自动处理本地包关联，无需手动做路径映射。

5. 运行验证 #

• 清理历史缓存：yarn cache clean && rm -rf .yarn/install-state.gz
• 重新安装依赖：yarn install
• 构建global包：yarn tsc --build global
• 构建服务端：yarn tsc --build server
• 启动客户端：yarn workspace client dev
• 启动服务端：yarn workspace server start

原有monorepo结构完全保留，Yarn PnP会自动hoist重复依赖，不会再出现draft-js多实例引发的运行时问题。

内容的提问来源于stack exchange，提问作者Japser36