Mastering Yarn Monorepo: A Step‑by‑Step Guide to Scalable SDK Development

Several years ago I built simple SDK repositories with ESLint+Prettier+GitHook, Rollup, and a private npm registry. As the SDK grew to support multiple platforms and debugging tools, the original setup became painful, requiring manual directory isolation, repeated package.json version bumps, and shared tsconfig.json that couldn't enforce environment constraints.

Searching revealed that projects like Babel and React use a monorepo approach, often with Lerna, but my experience with Lerna was unsatisfactory. Recently I tried Yarn's workspace (Berry) to build a monorepo and share my findings.

Setup Process

After initializing a repository, the structure looks like:

- packages/
  - xxx/
    - package.json
    - README.md
- package.json
- .prettierrc
- .eslintrc.js
- .editorconfig
- commitlint.config.js
- README.md

Each package uses shared ESLint/Prettier configs and enjoys clear directory isolation.

Adding Yarn

Install Yarn globally and set the Berry version in the workspace:

npm i -g yarn

yarn set version berry

This creates .yarn/ and .yarnrc.yml files.

Yarn Configuration

Typical .yarnrc.yml settings for corporate proxy and private npm registry:

httpProxy: 'http://127.0.0.1:8899'
httpsProxy: 'http://127.0.0.1:8899'
npmAuthIdent: '${USER:-root}:${TOKEN:-123456}'
npmPublishRegistry: 'https://mirrors.cn/npm/'
npmRegistryServer: 'https://mirrors.cn/npm/'
unsafeHttpWhitelist:
  - mirrors.cn
yarnPath: .yarn/releases/yarn-berry.cjs

Add workspaces to package.json:

{
  "workspaces": ["packages/*"]
}

IDE Configuration

If PnP mode is enabled, run:

yarn dlx @yarnpkg/pnpify --sdk vscode

Plugins

Import essential plugins:

yarn plugin import typescript
yarn plugin import workspace-tools
yarn plugin import version

These add entries to .yarnrc.yml under plugins.

TypeScript Configurations

Define environment‑specific tsconfig files (isomorphic, node, web) that extend a base config and set appropriate compiler options, paths, and type roots.

Package Scaffolding

Use naming conventions such as cli, core-xxx, plugin-xxx, utils-xxx, server-xxx, devtool-xxx and add a script like "addpkg": "yo xxx" to generate new packages.

Release Workflow

Unified versioning and publishing can be done with workspace scripts:

"ws:ver": "yarn workspaces foreach --exclude '+(server-*)' -pv exec npm version"
"ws:pub": "yarn workspaces foreach --exclude '+(server-*)' -vt npm publish --tag alpha --tolerate-republish"
"ws:prebuild": "yarn workspaces foreach -j 1000 -pvA run prebuild"
"ws:dev": "yarn workspaces foreach -j 1000 -pvA run dev"
"ws:dist": "yarn workspaces foreach -pvtA run dist"

These commands handle version bumps, publishing, and parallel builds across all packages.

Usage Experience

Dependency Management

Yarn offers offline cache, Plug’n’Play, and zero‑install features. I disabled PnP for better compatibility and set nodeLinker: node-modules in .yarnrc.yml, resulting in a conventional node_modules/ layout.

Workspace Commands

The yarn workspaces foreach command can run tasks topologically with the -topological flag, though long‑running processes like tsc -w can block the workflow.

Linking

Both npm link and Yarn’s resolution‑based linking have limitations, but simple symlinks often suffice.

Conclusion

These are my practical insights from using Yarn Monorepo. I prefer Yarn over pnpm due to its mature codebase and backing from large companies.

References:

JavaScript 包管理器简史（npm/yarn/pnpm）

为什么现在我更推荐 pnpm 而不是 npm/yarn

https://github.com/yarnpkg/yarn/issues/1761