Yarn Workspaces - Monorepo Setup That Actually Works

Remember trying to work on a shared component library? You'd make a change, publish a test version to npm, wait for it to sync, update your app's package.json, install, then discover your change broke everything. Repeat 47 times until you want to throw your laptop out the window.

Workspaces solve this by symlinking your packages locally. Change your component library, and your app sees it instantly. No publishing, no waiting, no version juggling. It's magic when it works.

The Pre-Workspace Nightmare

Before workspaces, managing multiple related packages was pure hell:

You'd have my-ui-lib, my-utils, and my-app in separate repos. Want to add a prop to a component? Edit the component, commit, publish to npm, bump version in your app, install, test, find a bug, repeat. Each round trip took 5-10 minutes. I've burned entire afternoons on simple changes.

Different packages inevitably ended up with conflicting dependency versions. Your UI lib uses React 17, your app uses React 18, your utils package somehow pulled in React 16. Good fucking luck debugging that mess.

CI/CD becomes a coordination nightmare. You can't just deploy your app - you need to ensure all dependencies are published first, in the right order, with compatible versions. One typo in a package name and your entire deployment pipeline explodes.

How Workspaces Actually Work

When you run `yarn install` in a workspace repo, Yarn does something clever. It reads all the package.json files, figures out which dependencies overlap, and installs shared ones at the root. Then it creates symlinks so each package can find what it needs.

Your project structure looks like this:

my-monorepo/
├── node_modules/        # Shared dependencies live here
├── packages/
│   ├── ui-lib/          # This is symlinked as node_modules/@company/ui-lib
│   └── utils/           # This is symlinked as node_modules/@company/utils
└── apps/
    └── web-app/         # Can import from @company/ui-lib directly

The symlinking is what makes changes appear instantly. Edit a file in packages/ui-lib, and your app sees it immediately because it's just following a symbolic link.

When It Actually Helps

Component libraries: Perfect. Build your components, storybook, and example apps all in one repo. No more test releases.

Shared utilities: Backend services sharing database models, validation schemas, or common middleware. Change once, use everywhere, deploy independently.

Design systems: UI components, design tokens, icons, and documentation sites all living together. Changes propagate instantly across all consuming applications.

Full-stack apps: Share TypeScript types between frontend and backend. Change your API response shape, and your frontend sees the new types immediately.

The Learning Curve (It's Brutal)

Workspaces aren't intuitive. The first time you set them up, you'll spend a weekend figuring out why nothing works. Common stumbling blocks:

• Forgetting to use workspace:^ protocol in dependencies
• Mixing yarn/npm/pnpm commands (lockfile chaos ensues)
• TypeScript not recognizing workspace packages (need project references)
• Hot reloading breaking mysteriously
• Circular dependencies that aren't obvious until everything breaks

Budget 2-3 weeks before workspaces feel natural. The payoff is worth it, but the initial frustration is real. I've seen senior engineers rage quit workspace migrations after hitting their 5th cryptic error message.

Once you get it working though, the productivity boost is addictive. No more publishing test versions. No more dependency hell. No more waiting for npm to sync. Just edit code and watch everything update in real-time.

The Basic Structure That Actually Works

Don't overthink the folder structure. Here's what works in practice:

my-monorepo/
├── package.json              # Root config - keep it simple
├── .yarnrc.yml              # Optional, but saves headaches later
├── apps/                    # Things you deploy
│   ├── web-app/
│   └── api-server/
├── packages/                # Things you share
│   ├── ui-components/
│   ├── shared-utils/
│   └── types/
└── tools/                   # Build stuff (optional)
    └── eslint-config/

Start simple. Add complexity when you actually need it, not because some blog post told you to.

Root package.json (The Part That Breaks Everything)

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ],
  "scripts": {
    "build": "yarn workspaces foreach -pt run build",
    "test": "yarn workspaces foreach run test",
    "dev": "yarn workspace web-app dev"
  },
  "devDependencies": {
    "typescript": "^5.2.0"
  }
}

Critical shit to remember:

• `"private": true` is mandatory. Forget this, and Yarn will yell at you
• Use `-pt` flags for builds (parallel + topological). Otherwise dependencies build in random order and break
• Don't version your root package.json. It's not published, so version numbers are meaningless

.yarnrc.yml (Skip This Initially)

Most tutorials dump a giant .yarnrc.yml config at you. Don't. Start without it. Add this later when you hit specific problems:

nodeLinker: node-modules
enableGlobalCache: true

That's it. The "advanced" config can wait until you actually understand what's breaking.

Workspace Dependencies (This Is Where It Gets Weird)

Instead of regular versions, use the `workspace:` protocol:

{
  "name": "web-app",
  "dependencies": {
    "ui-components": "workspace:*",
    "shared-utils": "workspace:^"
  }
}

The protocols:

• workspace:* - Use exact current version
• workspace:^ - Use compatible version range
• workspace:~ - Use compatible patch range

When you publish, Yarn converts these to real version numbers automatically. During development, they're just symlinks to your local code.

Common Setup Failures (And How to Fix Them)

"Cannot resolve module 'ui-components'"

Your workspace isn't linked properly. Run:

rm -rf node_modules yarn.lock
yarn install

If that doesn't work, check your package names. The dependency name in package.json must exactly match the "name" field in the target package.

TypeScript can't find workspace packages

You need project references. Add this to your root tsconfig.json:

{
  "references": [
    {"path": "./apps/web-app"},
    {"path": "./packages/ui-components"}
  ]
}

And in each package's tsconfig.json:

{
  "extends": "../../tsconfig.json",
  "references": [
    {"path": "../ui-components"}
  ]
}

Skip this and TypeScript compilation will be slow as hell.

Hot reload stops working

This happens constantly. First try restarting your dev server. If that doesn't work:

## Nuclear option
rm -rf node_modules .yarn/cache
yarn install

Sometimes symlinks get corrupted and only a full reinstall fixes it.

"yarn workspaces foreach" does nothing

You're using old Yarn. Upgrade to Yarn 3.x+:

yarn set version stable

Yarn 1.x uses yarn workspace (singular) with different syntax.

Commands You'll Actually Use

## Install everything
yarn install

## Add a dependency to specific workspace
yarn workspace ui-components add react

## Run script in all workspaces
yarn workspaces foreach run build

## Run script only in changed workspaces (requires git)
yarn workspaces foreach --since main run test

## Install only what's needed for one app (for Docker)
yarn workspaces focus web-app

That `--since` flag is magic for CI/CD. Only runs tests/builds in packages that actually changed.

Publishing (Don't Overthink It)

For most teams, manual publishing is fine:

## Version and publish specific packages
yarn workspace ui-components version patch
yarn workspace ui-components npm publish

If you need automated releases, install changesets. But get basic workspaces working first before adding more complexity.

The TypeScript Trap

TypeScript project references are mandatory for performance, but they're confusing as hell. Here's the minimal setup:

Root tsconfig.json:

{
  "references": [
    {"path": "./apps/web-app"},
    {"path": "./packages/ui-components"}
  ]
}

Each workspace tsconfig.json:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist"
  },
  "references": [
    {"path": "../ui-components"}
  ]
}

Skip the fancy path mapping. Let the symlinks do their job. Less configuration means fewer things to break.

The key insight: start simple, add complexity gradually, and expect to delete node_modules at least twice while figuring it out.