Monorepo with npm Workspaces

Advanced15 min

Set up and manage a monorepo using npm workspaces for shared packages, consistent tooling, and streamlined development.

Prerequisites

-Node.js 16 or later
-npm 7 or later

Steps

Initialize the monorepo root

Create the root package.json with workspaces configuration pointing to your package directories.

$ npm init -y && npm pkg set workspaces='["packages/*", "apps/*"]' && npm pkg set private=true

Always set private: true on the root package.json to prevent accidentally publishing the monorepo itself.

Create workspace packages

Set up individual packages within the monorepo with their own package.json files.

$ mkdir -p packages/shared apps/web apps/api npm init -y -w packages/shared npm init -y -w apps/web npm init -y -w apps/api

Add cross-workspace dependencies

Reference shared packages as dependencies in other workspaces using the workspace protocol.

$ npm pkg set dependencies.@myorg/shared="*" -w apps/web npm pkg set dependencies.@myorg/shared="*" -w apps/api npm install

npm automatically symlinks workspace packages. Changes to shared code are immediately available without publishing.

Run scripts across workspaces

Execute npm scripts in specific workspaces or across all workspaces from the root.

$ # Run in a specific workspace: npm run build -w apps/web # Run in all workspaces that have the script: npm run build --workspaces --if-present # Run tests everywhere: npm test --workspaces --if-present

Install dependencies to specific workspaces

Add dependencies to individual workspace packages rather than the root.

$ npm install express -w apps/api npm install react react-dom -w apps/web npm install typescript -w packages/shared

Install dependencies where they are used, not at the root. Root devDependencies should only be shared tooling like ESLint or TypeScript.

Create a shared TypeScript configuration

Set up a shared tsconfig that all workspace packages extend for consistent TypeScript settings.

$ cat <<'EOF' > packages/shared/tsconfig.base.json { "compilerOptions": { "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext", "declaration": true, "strict": true, "esModuleInterop": true, "skipLibCheck": true, "outDir": "dist" } } EOF # Extend in each workspace: cat <<'EOF' > apps/api/tsconfig.json { "extends": "../../packages/shared/tsconfig.base.json", "compilerOptions": { "outDir": "dist", "rootDir": "src" }, "include": ["src"] } EOF

Full Script

full-script.sh

#!/bin/bash
set -euo pipefail

# Node.js Monorepo Setup with npm Workspaces

ORG_NAME="${1:-myorg}"

echo "==> Initializing monorepo root..."
npm init -y
npm pkg set private=true
npm pkg set workspaces='["packages/*", "apps/*"]'
npm pkg set scripts.build="npm run build --workspaces --if-present"
npm pkg set scripts.test="npm run test --workspaces --if-present"
npm pkg set scripts.lint="npm run lint --workspaces --if-present"
npm pkg set scripts.clean="npm run clean --workspaces --if-present"

echo "==> Creating workspace directories..."
mkdir -p packages/shared/src apps/web/src apps/api/src

echo "==> Setting up shared package..."
cd packages/shared
npm init -y
npm pkg set name="@${ORG_NAME}/shared"
npm pkg set main="dist/index.js"
npm pkg set types="dist/index.d.ts"
npm pkg set scripts.build="tsc"
npm pkg set scripts.clean="rm -rf dist"

cat > src/index.ts <<'EOF'
export function formatDate(date: Date): string {
  return date.toISOString().split('T')[0];
}

export function slugify(text: string): string {
  return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
}
EOF
cd ../..

echo "==> Setting up API app..."
cd apps/api
npm init -y
npm pkg set name="@${ORG_NAME}/api"
npm pkg set scripts.build="tsc"
npm pkg set scripts.start="node dist/index.js"
npm pkg set scripts.dev="node --watch src/index.ts"

cat > src/index.ts <<'EOF'
import { formatDate } from '@myorg/shared';
console.log('API started at', formatDate(new Date()));
EOF
cd ../..

echo "==> Setting up Web app..."
cd apps/web
npm init -y
npm pkg set name="@${ORG_NAME}/web"
npm pkg set scripts.build="echo 'build web'"
npm pkg set scripts.dev="echo 'dev web'"
cd ../..

echo "==> Installing dependencies..."
npm install typescript -w packages/shared
npm install @${ORG_NAME}/shared -w apps/api
npm install @${ORG_NAME}/shared -w apps/web
npm install

echo ""
echo "==> Monorepo structure:"
find . -name 'package.json' -not -path '*/node_modules/*' | sort

echo ""
echo "==> Commands:"
echo "  npm run build               # Build all workspaces"
echo "  npm run build -w apps/api   # Build specific workspace"
echo "  npm test --workspaces       # Test all workspaces"
echo "  npm install pkg -w apps/api # Add dep to specific workspace"

FAQ

Discussion

Loading comments...

#!/bin/bash set -euo pipefail # Node.js Monorepo Setup with npm Workspaces ORG_NAME="${1:-myorg}" echo "==> Initializing monorepo root..." npm init -y npm pkg set private=true npm pkg set workspaces='["packages/*", "apps/*"]' npm pkg set scripts.build="npm run build --workspaces --if-present" npm pkg set scripts.test="npm run test --workspaces --if-present" npm pkg set scripts.lint="npm run lint --workspaces --if-present" npm pkg set scripts.clean="npm run clean --workspaces --if-present" echo "==> Creating workspace directories..." mkdir -p packages/shared/src apps/web/src apps/api/src echo "==> Setting up shared package..." cd packages/shared npm init -y npm pkg set name="@${ORG_NAME}/shared" npm pkg set main="dist/index.js" npm pkg set types="dist/index.d.ts" npm pkg set scripts.build="tsc" npm pkg set scripts.clean="rm -rf dist" cat > src/index.ts <<'EOF' export function formatDate(date: Date): string { return date.toISOString().split('T')[0]; } export function slugify(text: string): string { return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, ''); } EOF cd ../.. echo "==> Setting up API app..." cd apps/api npm init -y npm pkg set name="@${ORG_NAME}/api" npm pkg set scripts.build="tsc" npm pkg set scripts.start="node dist/index.js" npm pkg set scripts.dev="node --watch src/index.ts" cat > src/index.ts <<'EOF' import { formatDate } from '@myorg/shared'; console.log('API started at', formatDate(new Date())); EOF cd ../.. echo "==> Setting up Web app..." cd apps/web npm init -y npm pkg set name="@${ORG_NAME}/web" npm pkg set scripts.build="echo 'build web'" npm pkg set scripts.dev="echo 'dev web'" cd ../.. echo "==> Installing dependencies..." npm install typescript -w packages/shared npm install @${ORG_NAME}/shared -w apps/api npm install @${ORG_NAME}/shared -w apps/web npm install echo "" echo "==> Monorepo structure:" find . -name 'package.json' -not -path '*/node_modules/*' | sort echo "" echo "==> Commands:" echo " npm run build # Build all workspaces" echo " npm run build -w apps/api # Build specific workspace" echo " npm test --workspaces # Test all workspaces" echo " npm install pkg -w apps/api # Add dep to specific workspace"