Courses / Monorepo Tooling
1. pnpm workspace
pnpm's workspace mechanism for managing dependencies and linking packages inside a monorepo.
How It Works
Think of the repo as an apartment building: pnpm keeps a single warehouse of packages (the store) and places lightweight symlinked doors from each apartment to the shared goods or to neighboring apartments (local packages).
You list workspace package locations in the root pnpm-workspace.yaml or package.json workspaces field.
When you run pnpm install at the root, pnpm resolves and places package files in a global store on disk.
pnpm creates symlinks in each package's node_modules to point to the central store or to other local workspace packages.
Local workspace package versions satisfy local dependency specifiers and are linked instead of fetched from the registry.
See It
The code tries to read the symlink at packages/pkg-a/node_modules/pkg-b; in a pnpm workspace that links pkg-b into pkg-a, readlinkSync returns the target path (often a path into pnpm's store or the local package folder). Try modifying the path to check other workspace links like packages/pkg-b/node_modules/pkg-a.
/*
Run this in a folder with:
- pnpm installed
- packages/pkg-a/package.json and packages/pkg-b/package.json
This script prints the symlink target for a workspace dependency.
*/
const fs = require('fs');
const path = require('path');
const pkgBNode = path.resolve('packages/pkg-a/node_modules/pkg-b');
try {
const target = fs.readlinkSync(pkgBNode);
console.log('pkg-b is symlinked to:', target);
} catch (e) {
console.log('No symlink found—run `pnpm install` at repo root with workspaces configured.');
}Use It
Sharing a utilities package across multiple services in a monorepo while developing locally.
/*
Assume workspace:
- packages/utils (exports greet)
- packages/app (depends on "utils")
After pnpm install, app can require the local utils directly.
*/
const greet = require('utils').greet;
console.log(greet('world'));Because pnpm links the local utils package into the app's node_modules, you get instant local changes and a single installed copy of shared dependencies.
Break It
What will this print when both packages are in the workspace and pnpm install was run at root?
/*
Common misconception: setting a workspace dependency with a version number forces registry install.
packages/app/package.json:
"dependencies": { "utils": "1.0.0" }
Even with workspaces declared, this code assumes pnpm won't link the local package.
*/
const utils = require('utils');
console.log(typeof utils.greet);pnpm workspace linking prefers local workspace packages over the registry even if the dependency version is a concrete semver like "1.0.0", provided the local package's package.json name and compatible version match; pnpm will create a symlink so require('utils') resolves to the local package, exposing its exported function.
Ensure the local package's package.json name and version match the dependency, or use a workspace: prefix if you want to force local linking; change the dependency to "workspace:^1.0.0" to be explicit.
/*
Explicit workspace notation ensures local linking:
packages/app/package.json:
"dependencies": { "utils": "workspace:^1.0.0" }
*/
const utils = require('utils');
console.log(typeof utils.greet);Level Up
selective hoisting: Configure pnpm's packageExtensions and public-hoist-pattern to control which transitive deps are hoisted to the repo root to avoid version conflicts.
workspace protocols for dev vs prod: Use "workspace:" protocol for local development and switch to registry versions in CI by using pnpmfile or automated version bumps to ensure reproducible builds.
linking build outputs: Build packages into a dist folder and use "pnpm link" or workspace: to link built artifacts for testing production-like consumers.
Prove It
Create a small pnpm workspace with two packages (pkg-a depends on pkg-b). Write a Node.js script that prints the resolved path of pkg-b as seen by pkg-a (should be a symlink to the workspace package or store).
JavaScript
pnpm workspace
A pnpm workspace is a way to manage multiple related packages in one repo so dependencies are hoisted and local packages are linked automatically.
"I want my frontend and shared utils to install once and reference each other locally during development."
pnpm workspaces let you declare multiple packages in a monorepo so pnpm installs shared deps in a central store and symlinks local package folders into each other for fast, consistent development.
"I want my frontend and shared utils to install once and reference each other locally during development."
pnpm workspaces let you declare multiple packages in a monorepo so pnpm installs shared deps in a central store and symlinks local package folders into each other for fast, consistent development.