Workspaces & Monorepos

npm workspaces link internal packages in one repo so shared code ships without publishing to a registry for every change.

Recipe

Quick-reference recipe card - copy-paste ready.

{
  "name": "@acme/platform",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "npm run build -w @acme/shared && npm run build -w @acme/api"
  }
}

// apps/api/package.json
{
  "name": "@acme/api",
  "dependencies": {
    "@acme/shared": "workspace:*"
  }
}

When to reach for this:

• Multiple deployable services share TypeScript types or utilities.
• You want one lockfile and one npm ci for the whole org slice.
• Internal packages change in the same PR as their consumers.

Working Example

platform/
  package.json          # workspaces root
  package-lock.json
  apps/
    api/
      package.json      # @acme/api
      src/server.ts
  packages/
    shared/
      package.json      # @acme/shared
      src/index.ts

// packages/shared/package.json
{
  "name": "@acme/shared",
  "version": "0.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc -p tsconfig.json"
  }
}

// apps/api/src/server.ts
import { createLogger } from "@acme/shared";
 
const log = createLogger("api");
log.info("listening");

npm install          # links workspaces
npm run build -w @acme/shared
npm run dev -w @acme/api

What this demonstrates:

• workspace:* tells npm to symlink the local @acme/shared package.
• -w targets a single workspace without cd.
• Shared package builds before the API imports compiled output.

Deep Dive

How It Works

• Root workspaces globs discover package.json files under apps/* and packages/*.
• npm install hoists shared dependencies and symlinks internal packages into consumer node_modules.
• workspace:* resolves to the local version at install time; publishing replaces it with the concrete semver.
• One package-lock.json at the root captures the entire graph.

workspace: Protocol

TypeScript Notes

// packages/shared/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src"
  }
}

• Enable composite for project references across packages.
• Consumers should import from package names (@acme/shared), not relative paths into packages/shared/src.

Gotchas

• Importing source paths across packages - Bypasses package boundaries and breaks publish. Fix: export through package.json main/exports.
• Forgetting to build shared libs - API runs against stale dist/. Fix: order build scripts or use Turborepo pipeline deps.
• Phantom dependencies - Hoisting lets you import undeclared packages. Fix: consider pnpm or ESLint import-x/no-extraneous-dependencies.
• Version 0.0.0 internal packages - Fine for private monorepos; publishable libs need real semver before npm publish. Fix: run npm version in the package before external release.
• Circular workspace deps - @acme/a depends on @acme/b and vice versa. Fix: extract shared kernel to @acme/core.

Alternatives

FAQs

npm run test -w @acme/api
npm run build --workspaces --if-present

npm install zod -w @acme/api

Related

• Package Managers Basics - pnpm vs npm for monorepos
• Turborepo for Node - cached workspace builds
• Multi-Service Monorepo - service boundaries

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.