npm-workspaces

mcclowes's avatarfrom mcclowes

Use when managing npm workspaces monorepos - package dependencies, build ordering, cross-package development, and publishing workflows

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 21, 2025
[Developer Tools]

When & Why to Use This Skill

This Claude skill facilitates the efficient management of npm workspaces within monorepo environments. It automates complex tasks such as cross-package dependency resolution, build orchestration, and multi-package publishing workflows, ensuring a seamless development experience for large-scale JavaScript and TypeScript projects by optimizing the local development lifecycle.

Use Cases

  • Monorepo Initialization: Quickly configure a root package.json and directory structure to manage multiple interconnected packages under a single repository.
  • Dependency Synchronization: Automatically link local packages and manage shared dependencies to avoid version conflicts and reduce disk space usage across the workspace.
  • Orchestrated Build Pipelines: Execute build and test scripts across all or specific workspaces while maintaining the correct execution order based on internal package dependencies.
  • Streamlined Publishing: Simplify the versioning and deployment process for multiple packages to the npm registry using unified workspace commands.
namenpm-workspaces
descriptionUse when managing npm workspaces monorepos - package dependencies, build ordering, cross-package development, and publishing workflows

npm Workspaces

Quick Start

// Root package.json
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["packages/*"],
  "scripts": {
    "build": "npm run build --workspaces",
    "test": "npm run test --workspaces"
  }
}

Core Commands

Command Purpose
npm install Install all workspace deps
npm run build --workspaces Run in all workspaces
npm run build -w pkg-name Run in specific workspace
npm run build --if-present Skip if script missing

Cross-Package Dependencies

// packages/compiler/package.json
{
  "name": "my-compiler",
  "dependencies": {
    "my-parser": "^1.0.0"  // Reference sibling package
  }
}
  • Use semver (not file:) for publishable packages
  • npm symlinks local packages automatically
  • Build order matters: dependencies before dependents

Build Ordering

// Root package.json - explicit order
{
  "scripts": {
    "build": "npm run build -w my-parser && npm run build -w my-compiler && npm run build -w my-cli"
  }
}

Or use a tool like wireit or turbo for dependency-aware builds.

Publishing

# Update versions (from root)
npm version patch -w my-parser
npm version patch -w my-compiler

# Publish all
npm publish --workspaces

# Publish specific
npm publish -w my-parser

Tips

  • Use "private": true in root to prevent accidental publish
  • Run npm ls to verify dependency resolution
  • Use npm explain <pkg> to debug why a package is installed
  • Add engines field to enforce Node version
  • Use --include-workspace-root to also run in root