Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Monorepos

Monorepo Basics and Workspace Layout

Learn what a monorepo is, when to use one, how workspaces are declared in npm, Yarn and pnpm, and how a root install links local packages together.

A monorepo keeps several packages (a web app, an API, a UI library, shared utilities) in one git repository. Instead of publishing @acme/ui to a registry every time you tweak a button, the app simply uses the copy that sits next to it. One pull request can change the library and its consumers together, tests run against real code rather than a published snapshot, and tooling (lint, TypeScript, CI) is configured once.

npm, Yarn and pnpm all support this natively through workspaces. This lesson covers the layout, the declaration syntax in each manager, and what a root install does. Commands appear as read-only snippets; the runnable example builds a real workspace folder with Node's fs module and mimics the linking step.

When a monorepo helps (and when it does not)

Good fit Poor fit
Packages that change together (app + shared library) Unrelated projects with different owners and release cycles
One team or closely cooperating teams Strict access separation per project
You want atomic refactors across packages Very large repos with no build tooling to cope with the size
Shared tooling and conventions Teams that need totally different toolchains

A monorepo is not automatically better than several repos. It trades coordination cost for tooling cost. Workspaces are the light, built-in end of the scale; tools such as Turborepo and Nx sit on top for bigger repos (see filtering and task orchestration).

A typical layout

TEXT
acme/
โ”œโ”€โ”€ package.json            # root: private, declares workspaces
โ”œโ”€โ”€ package-lock.json       # one lockfile for everything
โ”œโ”€โ”€ apps/
โ”‚   โ”œโ”€โ”€ web/package.json    # name: @acme/web
โ”‚   โ””โ”€โ”€ api/package.json    # name: @acme/api
โ””โ”€โ”€ packages/
    โ”œโ”€โ”€ ui/package.json     # name: @acme/ui
    โ””โ”€โ”€ utils/package.json  # name: @acme/utils

Rules of thumb:

  • The root is "private": true. It holds shared devDependencies (TypeScript, ESLint, test runner) and scripts that fan out.
  • Every workspace has its own package.json with a unique name. A scope (@acme/) keeps them from clashing with public packages.
  • There is one lockfile, at the root. Do not create lockfiles inside workspaces.
  • Group by role (apps/ for things you deploy, packages/ for libraries) so globs stay simple.

Declaring workspaces

npm and Yarn

JSON
{
  "name": "acme",
  "private": true,
  "workspaces": ["apps/*", "packages/*"]
}

pnpm

pnpm reads a separate file, pnpm-workspace.yaml:

YAML
packages:
  - "apps/*"
  - "packages/*"
  - "!**/fixtures/**"     # exclusion

The glob patterns pick directories that contain a package.json. All three managers support * (one level) and ** (any depth), and pnpm supports ! exclusions.

What a root install does

When you run npm install (or yarn, or pnpm install) at the root:

  1. It finds every workspace by evaluating the globs.
  2. It merges the dependency requests of all workspaces and resolves them together, writing one lockfile.
  3. It installs external packages (hoisted to the root node_modules by npm and Yarn Classic; kept in a content-addressable store and linked by pnpm, see node_modules layouts).
  4. It links the workspaces themselves into node_modules: node_modules/@acme/ui becomes a symlink to packages/ui.

Step 4 is why import '@acme/ui' in the web app finds the local source instead of a registry download, and why edits show up instantly without republishing.

This example creates a real workspace tree in a temporary directory, finds the workspaces from the glob list and creates the symlinks, then prints the resulting tree. It is a stand-in for what the package manager does.

Node.js Stand-in: discover workspaces and link them

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Running commands in workspaces

Terminal
npm run build --workspaces            # every workspace that has a build script
npm run build -w packages/ui          # one workspace, by folder or name
npm install lodash -w @acme/api       # add a dependency to one workspace
npm install -D typescript             # add to the root

yarn workspace @acme/web add react    # Yarn
yarn workspaces foreach -A run build

pnpm --filter @acme/web add react     # pnpm
pnpm -r run build                     # recursive: every workspace

Put a dependency in the workspace that imports it, not in the root. The root should only hold tools used by everyone. This keeps each package's manifest honest (important when it is published) and lets the manager install only what a given workspace needs.

Seeing the graph

Workspaces depend on each other, and that graph decides build order: utils must build before ui, and ui before web.

flowchart LR
  utils["@acme/utils"] --> ui["@acme/ui"]
  ui --> web["@acme/web"]
  utils --> api["@acme/api"]

Build order follows the arrows: libraries first, apps last.

This stand-in computes a build order from the dependency data with a topological sort:

Node.js Stand-in: compute a build order

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Circular dependencies between workspaces break build ordering and make publishing confusing. If two packages need each other, extract the shared part into a third.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do the workspace globs live in a pnpm monorepo?

    npm and Yarn read the workspaces field in package.json; pnpm reads packages: in pnpm-workspace.yaml.
  2. 2. Why does import '@acme/ui' find local source after a root install?

    The install links each workspace package into node_modules, so resolution finds the folder next to your code.
  3. 3. Where should a dependency used only by packages/ui be declared?

    Declare dependencies where they are imported. The root holds shared tooling only.
  4. 4. How many lockfiles should a workspace monorepo have?

    All workspaces are resolved together, so there is a single root lockfile.

Summary

  • A monorepo keeps related packages in one repository; workspaces are the built-in support in npm, Yarn and pnpm.
  • Declare globs in workspaces (npm, Yarn) or pnpm-workspace.yaml; keep the root private.
  • A root install resolves everything together, writes one lockfile and links workspaces into node_modules.
  • Declare dependencies in the workspace that uses them; avoid cycles.
  • The dependency graph defines build order.

Next: Workspace Protocol and Local Linking