Quickstart Guide

Get started with WooCommerce development in under 10 minutes.

Overview

This quickstart will get you from zero to a working WooCommerce development environment with your first customization in under 10 minutes.

This guide assumes you have basic familiarity with Git, command line, and either PHP or JavaScript development.

Prerequisites

Before you begin, ensure you have:

1. Node.js (via NVM)

   Install Node Version Manager to manage Node.js versions:

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

   Install PNPM package manager globally:

   npm install -g pnpm
   
3. PHP 7.4+ and Composer

   Install PHP and Composer for your operating system:

   Ubuntu/Debian

   sudo apt update
   sudo apt install php php-cli php-mbstring php-xml composer
   

   macOS (Homebrew)

   brew install php composer
   

Get Started in Three Steps

Step 1: Clone and Install

Clone the WooCommerce repository and install dependencies:

# Clone the repository
git clone https://github.com/woocommerce/woocommerce.git
cd woocommerce

# Install the correct Node.js version
nvm install

# Install all dependencies (this may take a few minutes)
pnpm install

# Build all packages and plugins
pnpm build

The pnpm install command installs dependencies for all packages in the monorepo. The pnpm build command compiles TypeScript, bundles JavaScript, and prepares all packages for development.

Step 2: Start WordPress Environment

Start a local WordPress development environment with WooCommerce:

# Navigate to the WooCommerce plugin directory
cd plugins/woocommerce

# Start the WordPress environment (requires Docker)
pnpm -- wp-env start

First start will take 5-10 minutes as Docker downloads WordPress and sets up the database. Subsequent starts are much faster.

Once started, access your development site:

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

Step 3: Make Your First Change

Let’s add a custom message to the WooCommerce product page:

1. Create a custom plugin

   Create a new file plugins/woocommerce/.wordpress-org/local-plugins/wc-quickstart.php:

   <?php
   /**
    * Plugin Name: WooCommerce Quickstart
    * Description: My first WooCommerce customization
    * Version: 1.0.0
    */
   
   // Add a message after the product title
   add_action( 'woocommerce_single_product_summary', function() {
       echo '<p style="color: #843cfb; font-weight: bold;">'
          . 'Custom message from my quickstart plugin!'
          . '</p>';
   }, 6 );
   
2. Activate the plugin

   Visit http://localhost:8888/wp-admin/plugins.php and activate “WooCommerce Quickstart”.

3. View your change

   Visit any product page at http://localhost:8888/shop/ and see your custom message appear below the product title!

Congratulations! You’ve just created your first WooCommerce customization using action hooks.

What You Just Did

Let’s break down the hook you used:

add_action( 'woocommerce_single_product_summary', function() {
    // Your custom code
}, 6 );

• add_action(): Hooks your function into a specific WooCommerce action
• woocommerce_single_product_summary: The hook that fires on product pages
• Function: Your custom code to execute
• 6: Priority (controls when your code runs relative to other hooked functions)

WooCommerce has hundreds of hooks like this that let you customize every aspect of the store without modifying core code.

Next Steps

Now that you have a working environment, here’s what to explore next:

Learn About Hooks

Master WooCommerce’s extensive hook system

Build an Extension

Create a complete WooCommerce extension

Explore the REST API

Integrate with products, orders, and customers

Theme Development

Customize the storefront appearance

Common Development Tasks

Running Tests

# Run PHP tests
cd plugins/woocommerce
pnpm test:php

# Run JavaScript tests
pnpm test:js

Building Assets

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

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

# Watch for changes (auto-rebuild)
pnpm --filter='@woocommerce/plugin-woocommerce' start

Working with wp-env

# Stop the environment
pnpm -- wp-env stop

# Restart the environment
pnpm -- wp-env start

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

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

Troubleshooting

Port 8888 already in use

Another application is using port 8888. Stop it or configure wp-env to use different ports by editing .wp-env.json in plugins/woocommerce/.

Docker not running

wp-env requires Docker. Install Docker Desktop and ensure it’s running before starting wp-env.

Build errors

Try cleaning and reinstalling:

pnpm clean
pnpm install
pnpm build

PHP errors

Make sure you have all required PHP extensions:

php -m | grep -E 'mbstring|xml|curl|zip'

If any are missing, install them via your package manager.

Learn More

Development Environment

Detailed environment setup guide

Project Structure

Understanding the monorepo

Architecture

Learn WooCommerce architecture

Get Help

Stuck? Here’s where to get help:

• WooCommerce Slack: Join the developer community
• GitHub Discussions: Ask questions and share ideas
• Developer Blog: Stay updated with development news