Constructive PNPM

PNPM monorepo workspaces, publishing with makage, and large-scale monorepo management following Constructive conventions. This skill covers the full lifecycle of TypeScript/JavaScript package development in PNPM workspaces.

When to Apply

Use this skill when:

• Creating workspaces: Setting up new PNPM monorepos, configuring workspace structure
• Managing packages: Internal dependencies, filtering, selective builds, dependency updates
• Publishing: Building with makage, versioning with lerna, publishing to npm
• Scaling: Organizing large codebases, CI/CD patterns, build optimization

Quick Start

# Create workspace
mkdir my-workspace && cd my-workspace
pnpm init

# Configure workspace
cat > pnpm-workspace.yaml << 'EOF'
packages:
  - 'packages/*'
EOF

# Create a package
mkdir -p packages/my-lib/src
cd packages/my-lib && pnpm init

# Install dependencies
cd ../.. && pnpm install

# Build all packages
pnpm -r run build

Workspace Structure

my-workspace/
├── .eslintrc.json
├── .gitignore
├── .prettierrc.json
├── lerna.json
├── package.json            # private: true, pnpm -r scripts
├── packages/
│   ├── package-a/
│   │   ├── package.json
│   │   ├── src/
│   │   └── tsconfig.json
│   └── package-b/
│       ├── package.json
│       ├── src/
│       └── tsconfig.json
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
└── tsconfig.json

Core Configuration

Root package.json

{
  "name": "my-workspace",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "build": "pnpm -r run build",
    "clean": "pnpm -r run clean",
    "test": "pnpm -r run test",
    "lint": "pnpm -r run lint",
    "deps": "pnpm up -r -i -L"
  }
}

Key: root is always private: true, scripts use pnpm -r for recursive execution.

Internal Dependencies

{
  "dependencies": {
    "my-other-package": "workspace:*"
  }
}

When published, workspace:* is replaced with the actual version number.

Publishing with Makage

Constructive publishes from dist/ folder using makage to prevent tree-shaking into weird import paths.

Package Configuration

{
  "name": "my-package",
  "version": "0.1.0",
  "main": "index.js",
  "module": "esm/index.js",
  "types": "index.d.ts",
  "publishConfig": {
    "access": "public",
    "directory": "dist"
  },
  "scripts": {
    "clean": "makage clean",
    "build": "makage build",
    "prepublishOnly": "npm run build"
  },
  "devDependencies": {
    "makage": "0.1.10"
  }
}

Anti-Pattern: ESM-Only with Exports Map

NEVER use the exports map pattern — it breaks CommonJS consumers, exposes dist/ in import paths, and is incompatible with dist-folder publishing.

Anti-Pattern: Manual Build Scripts

NEVER use manual build scripts with rimraf/copyfiles — makage handles all of this automatically.

Deep Nested Imports

Deep nested imports via file path are fully supported and recommended for tree-shaking:

import { OrmClient } from '@my-org/sdk/api';
import { AdminClient } from '@my-org/sdk/admin';

Publishing Workflow

# 1. Build and test
pnpm install && pnpm -r run build && pnpm -r run test

# 2. Version (interactive)
pnpm lerna version

# 3. Publish
pnpm lerna publish from-package

Key Commands

| Command | Description | |---------|-------------| | pnpm install | Install all dependencies | | pnpm -r run build | Build all packages | | pnpm -r run test | Test all packages | | pnpm --filter <pkg> run <cmd> | Run in specific package | | pnpm --filter <pkg>... run <cmd> | Run in package and dependencies | | pnpm add <dep> --filter <pkg> | Add dependency to package | | pnpm add <dep> -w | Add dependency to root | | pnpm up -r -i -L | Interactive dependency update | | pnpm lerna version | Version packages | | pnpm lerna publish from-package | Publish packages |

Filtering and Selective Builds

pnpm --filter my-app run build           # Single package
pnpm --filter my-app... run build         # Package + dependencies
pnpm --filter "...[origin/main]" run build # Changed since main
pnpm --filter "!my-legacy" run build      # Exclude package

Troubleshooting Quick Reference

| Issue | Quick Fix | |-------|-----------| | Package not found after publish | Ensure publishConfig.directory is "dist" | | Types not found | Ensure types points to declaration file | | ESM import errors | Ensure module points to ESM build | | Dependency resolution issues | pnpm store prune && rm -rf node_modules && pnpm install | | Workspace link issues | pnpm why <package-name> |

Reference Guide

Consult these reference files for detailed documentation on specific topics:

| Reference | Topic | Consult When | |-----------|-------|--------------| | references/workspace.md | Workspace creation and configuration | Setting up a new monorepo, configuring pnpm-workspace.yaml, TypeScript config | | references/publishing.md | Publishing with makage and lerna | Building packages, dist-folder pattern, versioning, npm publishing | | references/monorepo-management.md | Large monorepo management | Filtering, selective builds, dependency management, CI/CD patterns, hybrid workspaces |

Cross-References

Related skills (separate from this skill):

• pgpm (references/workspace.md) — SQL module workspaces (PGPM uses pnpm under the hood)
• pgpm (references/publishing.md) — Publishing pgpm modules to npm
• constructive-boilerplate-pgpm-init — Workspace initialization templates