Yarn: Workspaces, Plug’n’Play, and Team Migration

Yarn

Yarn is a package manager with workspace, dependency-resolution, and installation features that can make a JavaScript project reproducible. Choose the Yarn version and installation mode deliberately. Modern Yarn and Yarn Classic have different workflows; a command that works in an old tutorial may not describe your team's installation.

Start with one small workspace boundary, a pinned tool version, and a clean-install check. Then test the actual editor, build, test, and deployment paths before moving a larger repository.

TL;DR

Pin the package-manager version and commit the intended lockfile.
Use workspace protocols for explicit local package relationships.
Treat PnP versus node_modules as a tooling decision to test.
Use immutable installs to reject unexpected lockfile changes in CI.
Keep constraints, dependency trust, and runtime behavior as separate checks.

Quick Example

This complete Node.js script writes a disposable two-workspace fixture in a new yarn-demo directory under the current directory. It refuses to reuse an existing directory and requires no downloaded application dependencies. Save it as make-demo.cjs and run it with Node 24.

Using Yarn 4.18.1, enter the new directory and run yarn install, yarn workspace @demo/app check, then yarn install --immutable. The empty lockfile establishes a project boundary when the fixture is nested under another project. These commands install only the fixture's local workspaces; no publishing step is involved.

Core Concepts

Workspaces describe packages inside a project

The root declares package locations; each child still declares its own dependencies. The workspace guide describes local references and the workspace: protocol, including how dependency ranges are rewritten when packages are published. A workspace directory is not a substitute for a correct dependency declaration.

PnP changes resolution

Modern Yarn's default PnP mode uses a generated loader instead of a conventional node_modules tree. Tools that assume filesystem layouts may need configuration or a supported alternative install mode. The PnP guide documents this boundary. Keep editor language services and packaged deployment artifacts in the pilot, not just a successful terminal import.

Constraints express repository policy

Modern JavaScript constraints can check workspace dependency and manifest fields. They do not establish that arbitrary transitive code is trustworthy or that every runtime path works. The constraints guide explains the declarative checks and their supported scope.

Migrate Through a Representative Workflow

The install command reference describes immutable behavior and the resolution/fetch/link/build phases. A lockfile is evidence of a resolved graph, not proof that a package is safe. Lifecycle scripts and registry credentials need their own reviewed policy.

Make the migration reversible while it is still a branch change: retain the prior tool and lockfile in history, document version pinning, and run the same acceptance route before and after. Avoid combining a package-manager change with broad dependency upgrades unless that combined scope is intentional.

In a mixed team, verify Windows, macOS/Linux, editor integrations, and CI agents that are actually supported. The tiny fixture demonstrates one local package relationship; it does not validate native addons, published workspaces, or production deployment packaging.

Best Practices

Declare the direct dependency

Add imports to the package that uses them. A dependency accidentally available through another package can disappear when the graph changes. Use the install mode's diagnostics to repair that declaration rather than weakening resolution globally.

Keep caches subordinate to the lock

Test a clean install and an expected cache miss. Cache hits should shorten work without becoming the only route to a valid build. Scope cache keys to the relevant lock, tool version, and platform assumptions.

Review constraints as code

Keep rules small, explain why they exist, and show a failing example. Automated fixing changes manifests; review the diff before treating it as a completed upgrade. Separate policy failures from runtime test failures so teams know what to repair.

Common Mistakes

Bad: Adopt PnP after testing only one Node import.

Correct: Exercise the editor, bundler, tests, native dependencies, and final artifact.

Bad: Let CI rewrite the lockfile silently.

Correct: Use a pinned version and immutable install with a reviewed update workflow.

Bad: Treat constraints as a dependency security review.

Correct: Use them for supported repository policies and retain supply-chain controls separately.

FAQ

Must Yarn use PnP?

Modern Yarn supports alternative install modes. Choose from measured compatibility and maintenance needs.

Does workspace:* publish another workspace by accident?

The protocol describes a dependency relationship. Publishing is a separate authorized workflow; inspect its range rewriting when packaging libraries.

Does the fixture compare package-manager speed?

No. It checks a small local workspace and lock workflow, without timing or disk rankings.

When should migration pause?

Pause when a required build, editor, or deployment integration fails the agreed pilot; resolve it or choose a supported installation mode before wider rollout.