Development Environment Setup

Set up your local development environment for WooCommerce development.

Overview

This guide will help you set up a complete development environment for working with the WooCommerce monorepo. Whether you’re building extensions, themes, or contributing to core, you’ll need these tools installed.

Prerequisites

Operating System

A POSIX-compliant operating system (Linux or macOS) is recommended. Windows users should use WSL (Windows Subsystem for Linux) available since Windows 10.

Required Tools

1. Node Version Manager (NVM)

   NVM ensures you’re using the correct Node.js version for WooCommerce development.

   Installation:

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   

   Verify installation:

   nvm --version
   

   The WooCommerce repository contains an .nvmrc file that specifies the required Node.js version.

2. PNPM Package Manager

   PNPM is used to manage dependencies and run scripts in the monorepo.

   Installation:

   npm

   npm install -g pnpm
   

   Verify installation:

   pnpm --version
   # Should show 9.15.0 or higher
   
3. PHP 7.4 or Higher

   WooCommerce requires PHP 7.4+ for development and runtime.

   Check existing PHP:

   php --version
   

   Installation (Ubuntu/Debian):

   sudo apt update
   sudo apt install php php-bcmath php-curl php-imagick \
                    php-intl php-json php-mbstring \
                    php-mysql php-xml php-zip
   

   Installation (macOS with Homebrew):

   brew install php@8.1
   

   Make sure you install the required PHP extensions: bcmath, curl, imagick, intl, json, mbstring, mysql, xml, and zip.

4. Composer Dependency Manager

   Composer manages PHP dependencies for WooCommerce and its packages.

   Installation:

   curl -sS https://getcomposer.org/installer | php
   sudo mv composer.phar /usr/local/bin/composer
   

   Verify installation:

   composer --version
   

Clone the Repository

Once all prerequisites are installed, clone the WooCommerce monorepo:

git clone https://github.com/woocommerce/woocommerce.git
cd woocommerce

Install Dependencies

1. Set Node.js version

   Use the version specified in .nvmrc:

   nvm install
   

   This will install and activate the correct Node.js version.

2. Install all dependencies

   Install PHP and JavaScript dependencies for all packages:

   pnpm install
   

   This command installs dependencies for all plugins, packages, and tools in the monorepo. It may take a few minutes.

3. Build all packages

   Build all plugins, packages, and tools:

   pnpm build
   

   This compiles TypeScript, bundles JavaScript, and prepares all packages for development.

WordPress Development Environment

For plugin development and testing, you’ll need a WordPress installation. WooCommerce uses @wordpress/env for local WordPress environments.

Setting Up wp-env

1. Navigate to the plugin directory

   cd plugins/woocommerce
   
2. Start the environment

   pnpm -- wp-env start
   

   This creates a Docker-based WordPress environment with WooCommerce installed.

   First start may take several minutes as Docker images are downloaded.

3. Access your development site

   After starting, your site will be available at:

   • Site URL: http://localhost:8888
   • Admin URL: http://localhost:8888/wp-admin
   • Username: admin
   • Password: password

wp-env Commands

# Start the environment
pnpm -- wp-env start

# Stop the environment
pnpm -- wp-env stop

# Destroy the environment (removes all data)
pnpm -- wp-env destroy

# Clean the environment (reset database)
pnpm -- wp-env clean

# Run WP-CLI commands
pnpm -- wp-env run cli wp plugin list

Docker Required: wp-env requires Docker Desktop (or Docker Engine + Docker Compose). Install from docker.com.

IDE Setup

Recommended IDEs

• Visual Studio Code: Popular, with excellent PHP and JavaScript support
• PHPStorm: Professional PHP IDE with deep WordPress integration
• Cursor: AI-powered editor based on VS Code

VS Code Extensions

Recommended extensions for WooCommerce development:

{
  "recommendations": [
    "bmewburn.vscode-intelephense-client",  // PHP IntelliSense
    "dbaeumer.vscode-eslint",               // ESLint
    "esbenp.prettier-vscode",               // Prettier
    "bradlc.vscode-tailwindcss",            // Tailwind CSS
    "ms-azuretools.vscode-docker"           // Docker support
  ]
}

EditorConfig

The repository includes an .editorconfig file that enforces consistent coding styles:

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = tab
indent_size = 4

Environment Verification

Verify your setup is complete:

Verification Checklist

# Check Node.js version
node --version
# Should match version in .nvmrc (^20.11.1)

# Check PNPM
pnpm --version
# Should be 9.15.0 or higher

# Check PHP
php --version
# Should be 7.4 or higher

# Check Composer
composer --version

# Check Docker (if using wp-env)
docker --version
docker-compose --version

# Verify build completed
ls plugins/woocommerce/build
# Should show compiled assets

Troubleshooting

PHP Extensions Missing

If you see errors about missing PHP extensions:

Ubuntu/Debian

sudo apt install php-bcmath php-curl php-imagick \
                 php-intl php-json php-mbstring \
                 php-mysql php-xml php-zip

macOS

pecl install imagick
brew install php@8.1

PNPM Install Fails

If pnpm install fails:

# Clear PNPM cache
pnpm store prune

# Try installing again
pnpm install

Docker Issues with wp-env

If wp-env won’t start:

# Check Docker is running
docker ps

# Stop conflicting containers
docker stop $(docker ps -aq)

# Try starting again
pnpm -- wp-env start

Port Conflicts

If port 8888 is already in use:

# Find what's using the port
lsof -i :8888

# Or configure wp-env to use different ports
# Edit .wp-env.json in plugins/woocommerce/

Next Steps

With your environment set up, you’re ready to start developing:

Project Structure

Learn about the monorepo organization

Extension Development

Start building extensions

Contributing

Contribute to WooCommerce core

Testing

Learn about testing requirements

Additional Resources

• PNPM Workspace Documentation
• WordPress wp-env Documentation
• Docker Documentation
• WooCommerce Development Blog