Monorepo Workflow

Working with WooCommerce’s pnpm workspace-based monorepo structure

WooCommerce is organized as a monorepo containing multiple packages, plugins, and tools managed with pnpm workspaces.

Monorepo Structure

The WooCommerce monorepo contains:

• Backend: PHP in plugins/woocommerce/ (PSR-4, WordPress standards)
• Admin Client: React/TypeScript in client/admin/
• JavaScript Packages: Reusable packages in packages/js/*
• PHP Packages: Composer packages in packages/php/*
• Development Tools: Build and automation tools in tools/*

Workspace Configuration

The monorepo uses pnpm workspaces defined in pnpm-workspace.yaml:

pnpm-workspace.yaml

packages:
    - 'packages/js/*'
    - 'packages/php/*'
    - 'plugins/*'
    - 'plugins/woocommerce/client/admin'
    - 'plugins/woocommerce/client/blocks'
    - 'plugins/woocommerce/client/legacy'
    - 'plugins/woocommerce/client/blocks/bin/eslint-plugin-woocommerce'
    - 'tools/monorepo-merge'
    - 'tools/code-analyzer'
    - 'tools/compare-perf'
    - 'tools/package-release'
    - 'tools/cherry-pick'
    - 'tools/release-posts'
    - 'tools/storybook'
    - 'tools/monorepo-utils'

Root Package Configuration

The root package.json defines monorepo-wide scripts and dependencies:

package.json

{
  "name": "woocommerce-monorepo",
  "packageManager": "pnpm@9.15.0",
  "engines": {
    "node": "^20.11.1"
  },
  "scripts": {
    "build": "pnpm -r --workspace-concurrency=Infinity --stream '/^build:project:.*$/',
    "test": "pnpm -r test",
    "lint": "pnpm -r lint",
    "clean": "rimraf -g '**/node_modules' '**/.wireit' 'packages/*/*/vendor' 'plugins/*/vendor'",
    "clean:build": "rimraf -g 'packages/js/*/build' 'packages/js/*/build-*'"
  }
}

The monorepo uses pnpm 9.15.0 as the package manager. Make sure you have the correct version installed.

PNPM Workspaces

PNPM workspaces enable efficient dependency management across all packages.

Filtering Packages

Use the --filter flag to run commands on specific packages:

# Build WooCommerce Core and all dependencies
pnpm --filter='@woocommerce/plugin-woocommerce' build

# Lint a specific package
pnpm --filter='@woocommerce/components' lint

# Test all @woocommerce scoped packages
pnpm --filter='@woocommerce/*' test

# Build all JavaScript packages
pnpm --filter='./packages/js/*' build

# Build everything except WooCommerce Core
pnpm --filter='!@woocommerce/plugin-woocommerce' build

# Build everything that changed since last commit
pnpm --filter='[HEAD^1]' build

Workspace Dependencies

Packages can depend on other workspace packages:

{
  "dependencies": {
    "@woocommerce/components": "workspace:*",
    "@woocommerce/data": "workspace:*"
  }
}

The workspace:* protocol ensures packages use local versions during development and resolves to actual versions when published.

Build System

The monorepo uses multiple build tools depending on the package type.

JavaScript Build Tools

JavaScript packages use a combination of:

• Webpack: For bundling client applications
• TypeScript: For type-safe JavaScript
• Wireit: For incremental builds and caching
• Babel: For JavaScript transpilation

PHP Build Tools

PHP packages use:

• Composer: For PHP dependencies
• PHPStan: For static analysis
• PHPCS: For code style checking
• PHPUnit: For testing

Build Commands

Build All

# Build all packages in the monorepo
pnpm build

# Build and watch for changes
pnpm start

Build Specific Package

# Build WooCommerce Core
pnpm --filter='@woocommerce/plugin-woocommerce' build

# Build admin client
pnpm --filter='@woocommerce/admin-client' build

Clean Build

# Clean all build artifacts
pnpm clean:build

# Clean and rebuild
pnpm clean:build && pnpm build

Package Dependencies

The monorepo manages dependencies at multiple levels.

Dependency Resolution

PNPM creates a single node_modules structure with symlinks:

node_modules/
├── @woocommerce/
│   ├── components -> ../../packages/js/components
│   ├── data -> ../../packages/js/data
│   └── plugin-woocommerce -> ../../plugins/woocommerce
└── react

Shared Dependencies

Common dependencies are hoisted to the root to save disk space:

package.json

{
  "dependencies": {
    "@babel/core": "7.25.7",
    "lodash": "^4.17.21",
    "wp-textdomain": "1.0.1"
  },
  "pnpm": {
    "overrides": {
      "@types/react": "18.3.x",
      "@wordpress/data": "wp-6.6"
    }
  }
}

Version Synchronization

The monorepo uses syncpack to keep dependencies aligned:

# Check for version mismatches
pnpm sync-dependencies

Development Scripts

Common development tasks have dedicated scripts.

Testing Scripts

# Run PHP unit tests (from plugins/woocommerce)
pnpm test:php:env -- --filter TestClassName

# Run JavaScript tests
pnpm --filter='@woocommerce/components' test

# Run all tests
pnpm test

Linting Scripts

# Lint all packages
pnpm lint

# Lint changed PHP files only
pnpm --filter='@woocommerce/plugin-woocommerce' lint:php:changes

# Fix linting issues
pnpm --filter='@woocommerce/plugin-woocommerce' lint:php:fix -- path/to/file.php

# Run PHPStan analysis (from plugins/woocommerce)
composer exec -- phpstan analyse src/Internal/MyClass.php --memory-limit=2G

Changelog Scripts

Always create changelog entries before creating a pull request. PRs without changelog entries will fail CI checks.

# Add changelog entry for WooCommerce Core
pnpm --filter='@woocommerce/plugin-woocommerce' changelog add

# Add changelog for specific package
pnpm --filter='@woocommerce/components' changelog add

Development Tools

The tools/ directory contains utilities for monorepo development.

Monorepo Utils

Command-line tools for common tasks:

# Run monorepo utilities
pnpm utils <command>

Code Analyzer

Analyze code changes and dependencies:

pnpm --filter='@woocommerce/code-analyzer' run analyze

Cherry Pick Tool

Backport changes between branches:

pnpm cherry-pick <commit-hash>

Common Workflows

1. Clone and Install

   git clone https://github.com/woocommerce/woocommerce.git
   cd woocommerce
   pnpm install
   
2. Build Everything

   # Initial build of all packages
   pnpm build
   
3. Start Development Environment

   # Navigate to plugin directory
   cd plugins/woocommerce
   
   # Start WordPress environment
   pnpm -- wp-env start
   
4. Make Changes and Test

   # Make code changes, then run tests
   pnpm test:php:env
   pnpm lint:php:changes
   
5. Create Changelog

   # Add changelog entry
   pnpm --filter='@woocommerce/plugin-woocommerce' changelog add
   

Package Organization

JavaScript Packages (packages/js/)

• @woocommerce/components: Reusable React components
• @woocommerce/data: Data stores and API client
• @woocommerce/navigation: Navigation utilities
• @woocommerce/date: Date manipulation utilities
• @woocommerce/currency: Currency formatting
• And many more…

PHP Packages (packages/php/)

• @woocommerce/blueprint: Blueprint specifications
• @woocommerce/email-editor: Email customization
• @woocommerce/remote-specs-validation: Remote spec validation

Plugins

• @woocommerce/plugin-woocommerce: WooCommerce Core
• @woocommerce/woocommerce-beta-tester: Beta testing plugin

Performance Optimization

Incremental Builds

Wireit enables incremental builds:

{
  "scripts": {
    "build": "wireit"
  },
  "wireit": {
    "build": {
      "dependencies": ["build:deps"],
      "files": ["src/**"],
      "output": ["build/**"]
    }
  }
}

Parallel Execution

PNPM runs independent tasks in parallel:

# Run tests in all packages concurrently
pnpm -r --parallel test

Build Caching

Wireit caches build outputs to skip unchanged packages:

# First build (slow)
pnpm build

# Second build (fast - uses cache)
pnpm build

Build caches are stored in .wireit directories. These are automatically cleaned by pnpm clean.

Troubleshooting

Clean Installation

If you encounter dependency issues:

# Remove all node_modules and reinstall
pnpm clean
pnpm install

Lock File Issues

If pnpm-lock.yaml gets out of sync:

# Regenerate lock file
rm pnpm-lock.yaml
pnpm install

Build Failures

If builds fail after pulling changes:

# Clean build artifacts and rebuild
pnpm clean:build
pnpm build

Next Steps

Architecture

Understand WooCommerce’s overall architecture

Modern vs Legacy

Learn about code organization patterns