Monorepo with npm Workspaces

Intermediate15 minTrending

Set up and manage a monorepo using npm workspaces to share code, dependencies, and scripts across multiple packages in a single repository.

Prerequisites

-Node.js 16+ and npm 7+ installed
-Basic package.json knowledge

Steps

Initialize the root package

Create the root package.json with workspace definitions.

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

The root package must have 'private: true' to prevent accidentally publishing the monorepo root.

Create workspace packages

Scaffold individual packages within the workspaces directory.

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

Add a dependency to a specific workspace

Install a package into one workspace without affecting others.

$ npm install express -w packages/api && npm install react react-dom -w packages/web

Link a workspace as a dependency

Reference one workspace package from another for code sharing.

$ npm install packages/shared -w packages/api && npm install packages/shared -w packages/web

npm automatically creates a symlink. The shared package will appear in the workspace's package.json as a regular dependency.

Run scripts across workspaces

Execute npm scripts in specific or all workspaces.

$ npm run build --workspaces && npm run test -w packages/api

Full Script

full-script.sh

#!/bin/bash
# npm Workspaces Monorepo Setup
set -euo pipefail

PROJECT=${1:?"Usage: $0 <project-name>"}

echo "=== Creating Monorepo: $PROJECT ==="
mkdir -p "$PROJECT" && cd "$PROJECT"

# Root package.json
npm init -y
npm pkg set private=true
npm pkg set workspaces='["packages/*"]'

# Create workspace packages
for pkg in shared api web; do
  mkdir -p "packages/$pkg/src"
  cd "packages/$pkg"
  npm init -y
  npm pkg set name="@$PROJECT/$pkg"
  echo "export {};" > src/index.ts
  cd ../..
done

# Link shared package to api and web
npm install "./packages/shared" -w "packages/api"
npm install "./packages/shared" -w "packages/web"

echo ""
echo "=== Workspace Structure ==="
find . -name 'package.json' -not -path '*/node_modules/*' | sort

echo ""
echo "=== Workspace Info ==="
npm ls --workspaces --depth=0

echo ""
echo "Monorepo created at $PROJECT/"

FAQ

Discussion

Loading comments...

#!/bin/bash # npm Workspaces Monorepo Setup set -euo pipefail PROJECT=${1:?"Usage: $0 <project-name>"} echo "=== Creating Monorepo: $PROJECT ===" mkdir -p "$PROJECT" && cd "$PROJECT" # Root package.json npm init -y npm pkg set private=true npm pkg set workspaces='["packages/*"]' # Create workspace packages for pkg in shared api web; do mkdir -p "packages/$pkg/src" cd "packages/$pkg" npm init -y npm pkg set name="@$PROJECT/$pkg" echo "export {};" > src/index.ts cd ../.. done # Link shared package to api and web npm install "./packages/shared" -w "packages/api" npm install "./packages/shared" -w "packages/web" echo "" echo "=== Workspace Structure ===" find . -name 'package.json' -not -path '*/node_modules/*' | sort echo "" echo "=== Workspace Info ===" npm ls --workspaces --depth=0 echo "" echo "Monorepo created at $PROJECT/"