SKILL.md

pnpm Development

You are an expert in pnpm, the fast, disk space efficient package manager for JavaScript and TypeScript projects.

Core Principles

Always use pnpm (not npm or yarn) for package management

Leverage pnpm's strict dependency resolution for better security

Use the content-addressable store for disk space efficiency

Maintain consistent lockfile (pnpm-lock.yaml)

Installation and Setup

Install pnpm globally: npm install -g pnpm

Or use corepack: corepack enable && corepack prepare pnpm@latest --activate

Specify pnpm version in package.json:

{

  "packageManager": "pnpm@9.0.0"

}

Workspace Configuration

Create pnpm-workspace.yaml for monorepo setup:

packages:

  - 'apps/*'

  - 'packages/*'

  - 'tooling/*'

Use glob patterns to define workspace package locations

All matched directories with package.json become workspace packages

Dependency Management

Install dependencies: pnpm install

Add dependencies to specific workspace:

pnpm add lodash --filter @org/my-app

pnpm add -D typescript --filter @org/my-lib

Use workspace protocol for internal dependencies:

{

  "dependencies": {

    "@org/shared-utils": "workspace:*",

    "@org/ui": "workspace:^"

  }

}

Protocol options:

workspace:* - Any version, replaced with actual version on publish

workspace:^ - Compatible versions

workspace:~ - Patch versions only

Filtering Commands

Run commands in specific packages:

pnpm --filter @org/my-app dev

pnpm --filter "./apps/*" build

pnpm --filter "...@org/my-lib" test  # Include dependents

pnpm --filter "@org/my-lib..." build  # Include dependencies

Filter patterns:

--filter <package-name> - Specific package

--filter "./path/*" - By path

--filter "...<pkg>" - Package and its dependents

--filter "<pkg>..." - Package and its dependencies

Scripts and Task Running

Run scripts across workspaces:

pnpm -r run build        # Run in all packages

pnpm -r --parallel run dev  # Run in parallel

pnpm -r --stream run test   # Stream output

Define root-level scripts for common operations:

{

  "scripts": {

    "build": "pnpm -r run build",

    "dev": "pnpm --filter @org/web dev",

    "lint": "pnpm -r run lint",

    "test": "pnpm -r run test"

  }

}

Dependency Hoisting

Configure hoisting in .npmrc:

# Strict mode - no hoisting

hoist=false

# Selective hoisting

public-hoist-pattern[]=*eslint*

public-hoist-pattern[]=*prettier*

# Shamefully hoist everything (not recommended)

shamefully-hoist=true

Prefer strict mode for better dependency isolation

Use public hoisting for tools that need flat node_modules

Peer Dependencies

Configure peer dependency handling in .npmrc:

auto-install-peers=true

strict-peer-dependencies=false

Resolve peer dependency warnings appropriately

Document required peer dependencies clearly

Overrides and Resolutions

Override dependencies in root package.json:

{

  "pnpm": {

    "overrides": {

      "lodash": "^4.17.21",

      "foo@1.x": "npm:bar@^2.0.0"

    }

  }

}

Use overrides to fix security vulnerabilities

Pin problematic transitive dependencies

Publishing Workspaces

Configure publishable packages with proper fields

Publish with pnpm publish

Workspace protocol references are replaced with actual versions

Performance Optimization

Use pnpm fetch in Docker for better caching:

COPY pnpm-lock.yaml ./

RUN pnpm fetch

COPY . ./

RUN pnpm install --offline

Configure store location for CI caching

Use --frozen-lockfile in CI environments

Best Practices

Always commit pnpm-lock.yaml

Use .npmrc for consistent team configuration

Prefer workspace:* for internal dependencies

Keep root package.json minimal

Use pnpm dedupe to optimize lockfile

Audit regularly with pnpm audit

Use pnpm why <package> to debug dependency issues

Integrate with Turborepo or Nx for advanced task running

Set engine-strict=true to enforce Node.js version requirements

pnpm