PNPM Workspaces (Constructive Standard)

Create and manage PNPM monorepo workspaces following Constructive conventions. This covers pure TypeScript/JavaScript workspaces (not pgpm workspaces for SQL modules).

When to Apply

Use this skill when:

Creating a new TypeScript/JavaScript monorepo
Setting up a pnpm workspace structure
Configuring lerna for versioning and publishing
Managing internal package dependencies

Workspace Structure

A Constructive-standard pnpm workspace:

text

my-workspace/
├── .eslintrc.json
├── .gitignore
├── .prettierrc.json
├── lerna.json
├── package.json
├── 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 Files

pnpm-workspace.yaml

Defines which directories contain packages:

yaml

packages:
  - 'packages/*'

For larger projects with multiple package directories:

yaml

packages:
  - 'packages/*'
  - 'apps/*'
  - 'libs/*'

Root package.json

json

{
  "name": "my-workspace",
  "version": "0.0.1",
  "private": true,
  "repository": {
    "type": "git",
    "url": "https://github.com/org/my-workspace"
  },
  "license": "MIT",
  "publishConfig": {
    "access": "restricted"
  },
  "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"
  },
  "devDependencies": {
    "@types/jest": "^30.0.0",
    "@types/node": "^22.10.2",
    "@typescript-eslint/eslint-plugin": "^8.53.1",
    "@typescript-eslint/parser": "^8.53.1",
    "eslint": "^9.39.2",
    "eslint-config-prettier": "^10.1.8",
    "jest": "^30.2.0",
    "lerna": "^8.2.4",
    "prettier": "^3.8.0",
    "ts-jest": "^29.4.6",
    "ts-node": "^10.9.2",
    "typescript": "^5.6.3"
  }
}

Key points:

Root package is
```
private: true
```
(never published)
Scripts use
```
pnpm -r
```
to run recursively across packages
```
deps
```
script for interactive dependency updates

lerna.json

json

{
  "$schema": "node_modules/lerna/schemas/lerna-schema.json",
  "version": "independent",
  "npmClient": "pnpm",
  "registry": "https://registry.npmjs.org",
  "command": {
    "create": {
      "homepage": "https://github.com/org/my-workspace",
      "license": "MIT",
      "access": "restricted"
    },
    "publish": {
      "allowBranch": "main",
      "message": "chore(release): publish",
      "conventionalCommits": true
    }
  }
}

Versioning modes:

```
"version": "independent"
```
— Each package versioned separately (recommended for utility libraries)
```
"version": "0.0.1"
```
— Fixed versioning, all packages share same version (recommended for tightly coupled packages)

Package Configuration

Individual package.json

json

{
  "name": "my-package",
  "version": "0.1.0",
  "description": "Package description",
  "author": "Constructive <developers@constructive.io>",
  "main": "index.js",
  "module": "esm/index.js",
  "types": "index.d.ts",
  "homepage": "https://github.com/org/my-workspace",
  "license": "MIT",
  "publishConfig": {
    "access": "public",
    "directory": "dist"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/org/my-workspace"
  },
  "scripts": {
    "clean": "makage clean",
    "build": "makage build",
    "lint": "eslint . --fix",
    "test": "jest"
  },
  "devDependencies": {
    "makage": "0.1.10"
  }
}

Key patterns:

```
publishConfig.directory: "dist"
```
— Publish from dist folder (prevents tree-shaking into weird paths)
```
main
```
and
```
module
```
point to built files (not src)
Uses makage for build tooling

Internal Dependencies

Reference workspace packages using

workspace:*

json

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

When published,

workspace:*

is replaced with the actual version number.

Common 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 build`	Build specific package
`pnpm up -r -i -L`	Interactive dependency update
`pnpm lerna version`	Version packages
`pnpm lerna publish`	Publish packages

Creating a New Package

bash

# Create package directory
mkdir -p packages/my-new-package/src

# Initialize package.json
cd packages/my-new-package
pnpm init

Then configure package.json following the pattern above.

TypeScript Configuration

Root tsconfig.json

json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "declaration": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  }
}

Package tsconfig.json

json

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

PNPM vs PGPM Workspaces

Aspect	PNPM Workspace	PGPM Workspace
Purpose	TypeScript/JS packages	SQL database modules
Config	pnpm-workspace.yaml	pnpm-workspace.yaml + pgpm.json
Build	makage build	pgpm package
Output	dist/ folder	SQL bundles
Registry	npm	npm (for @pgpm/* packages)

Some repos (like constructive) are hybrid — they have both pnpm packages and pgpm modules.

Best Practices

Keep root private: Never publish the root package
Use workspace protocol: Always use
```
workspace:*
```
for internal deps
Consistent structure: All packages follow same directory layout
Shared config: Extend root tsconfig.json in packages
Independent versioning: Use for utility libraries with different release cycles
Fixed versioning: Use for tightly coupled packages that should release together

References

Related skill:
```
pnpm-publishing
```
for publishing workflow with makage
Related skill:
```
pgpm-workspace
```
for SQL module workspaces
Related skill:
```
pgpm-publishing
```
for publishing pgpm modules

pnpm-workspace

NPX Install

Tags

SKILL.md Content

PNPM Workspaces (Constructive Standard)

When to Apply

Workspace Structure

Core Configuration Files

pnpm-workspace.yaml

Root package.json

lerna.json

Package Configuration

Individual package.json

Internal Dependencies

Common Commands

Creating a New Package

TypeScript Configuration

Root tsconfig.json

Package tsconfig.json

PNPM vs PGPM Workspaces

Best Practices

References