Setting up your development environment

Introduction

Creating a WooCommerce extension – which extends the WooCommerce plugin, or developing a theme for the WooCommerce plugin can be excellent ways to build custom functionality into your store and even monetize your development through the WooCommerce Marketplace.

This guide will walk you through the steps of getting a basic development environment set up for building WooCommerce extensions.

If you would like to contribute to the WooCommerce core platform; please read our contributor documentation and guidelines.

Prerequisites

WooCommerce does adhere to WordPress code standards and guidelines, so it’s best to familiarize yourself with WordPress Development as well as PHP.

Knowledge and understanding of WooCommerce Hooks and Filters will allow you to add and change code without editing core files. You can learn more about WordPress hooks and filters in the WordPress Plugin Development Handbook.

Recommended reading

WooCommerce extensions are a specialized type of WordPress plugin. If you are new to WordPress plugin development, take a look at a few of these articles in the WordPress Plugin Developer Handbook.

Required software

Git nvm NodeJS PNpm Composer

Note: If you’re working on a Windows machine, you may want to take a look at the Building Extensions in Windows Environments section of this guide before proceeding.

Setting up your reusable WordPress development environment

In addition to the software listed above, you’ll also want to have some way of setting up a local development server stack. There are a number of different tools available for this, each with a certain set of functionality and limitations. We recommend choosing an option below that fits your preferred workflow best.

WordPress-specific tools

vvv – A highly configurable, cross-platform, and robust environment management tool powered by VirtualBox and Vagrant. This is one tool that the WooCommerce Core team recommends to contributors.

wp-env – A command-line utility maintained by the WordPress community that allows you to set up and run custom WordPress environments with Docker and JSON manifests.

LocalWP – A cross-platform app that bills itself as a one-click WordPress installation.

General PHP-based web stack tools

MAMP – A local server environment that can be installed on Mac or Windows.

WAMP – A Windows web development environment that lets you create applications with Apache2, PHP, and MySQL.

XAMPP – An easy-to-install Apache distribution containing MariaDB, PHP, and Perl. It’s available for Windows, Linux, and OS X.

Minimum server requirements

Regardless of the tool you choose for managing your development environment, you should make sure it meets the server recommendations for WooCommerce as well as the requirements for running WordPress.

Anatomy of a WordPress development environment (public_html/)

While development environments can vary, the basic file structure for a WordPress environment should be consistent.

When developing a WooCommerce extension, you’ll usually be doing most of your work within the public_html directory of your local server. For now, take some time to familiarize yourself with a few key paths:

wp-content/debug.log – This is the file where WordPress writes the important output such as errors and other messages useful for debugging.

wp-content/plugins/ – This is the directory on the server where WordPress plugin folders live.

wp-content/themes/ – This is the directory on the server where WordPress theme folders live.

Adding WooCommerce Core to your environment

When developing an extension for WooCommerce, it’s helpful to install a development version of WooCommerce core.

Clone the WC Core repo into wp-content/plugins/

		cd /your/server/wp-content/plugins
git clone https://github.com/woocommerce/woocommerce.git
cd woocommerce

	

Activate the required Node version

		nvm use
Found '/path/to/woocommerce/.nvmrc' with version <v12>
Now using node v12.21.0 (npm v6.14.11)

	

Note: if you don’t have the required version of Node installed, NVM will alert you so you can install it:

		Found '/path/to/woocommerce/.nvmrc' with version <v12>
N/A: version "v12 -> N/A" is not yet installed.

You need to run "nvm install v12" to install it before using it.

	

Install dependencies

		pnpm install && composer install

	

Build WooCommerce

		pnpm build

	

Running this script will compile the JavaScript and CSS that WooCommerce needs to operate. If you try to run WooCommerce on your server without generating the compiled assets, you may experience errors and other unwanted side-effects.