woocommerce/DEVELOPMENT.md

WooCommerce Development Setup with WP-ENV

Docker development setup for WooCommerce with WP-ENV.

Prerequisites

Please install WP-ENV before getting started. You can find more about WP-ENV on here.

The following command installs WP-ENV globally.

npm -g i @wordpress/env

If you don't already have pnpm installed, you can quickly add it using NPM.

npm install -g pnpm

Starting WP-ENV

1. Navigate to the root of WooCommerce source code.
2. Start the docker container by running wp-env start

You should see the following output

WordPress development site started at http://localhost:8888/
WordPress test site started at http://localhost:8889/
MySQL is listening on port 55003

The port # might be different depending on your .wp-env.override.json configuration.

Getting Started with Developing

Once you have WP-ENV container up, we need to run a few commands to start developing.

1. Run pnpm install to install npm modules.
2. Run pnpm nx build woocommerce to build core.
3. Run pnpm nx composer-install woocommerce to install PHP dependencies.

If you don't have Composer available locally, run the following command. It runs the command in WP-ENV container.

wp-env run composer composer install

You might also want to run pnpm start to watch your CSS and JS changes if you are working on the frontend.

You're now ready to develop!

Typescript Checking

Typescript is progressively being implemented in this repository, and you might come across some files that are .ts or .tsx. By default, a VSCode environment will run type checking on such files that are currently open.

As of now, some parts of the codebase that were imported from the Woocommerce-Admin repository, into the plugins/woocommerce-admin/client directory, still fail Typescript checking. This has been scheduled on the team's backlog to be fixed.

In order to run type checking across the entire repository, you can run this command in your shell, from the root of this repository:

pnpm tsc -b tsconfig.base.json

For better developer experience, the folder .vscode/tasks.json has two VSCode tasks to run these commands automatically as well as to parse the output and highlight the errors in the Problems tab and in the file explorer pane. The first task runs it once, the second one runs it in the background upon saving of any modified files. This task is also automatically prompted by VSCode to be run upon opening the folder.

Using Xdebug

Please refer to WP-ENV official README section for setting up Xdebug.

Overriding the Default Configuration

The default configuration comes with PHP 7.4, WooCommerce 5.0, and a few WordPress config values.

You can create .wp-env.override.json file and override the default configuration values.

You can find more about .wp-env.override.json configuration here.

Example: Overriding PHP version to 8.0

Create .wp-env.override.json in the root directory with the following content.

{
	"phpVersion": "8.0"
}

Exampe: Adding a locally installed plugin

Method 1 - Adding to the plugins array

Open the default .wp-env.json and copy plugins array and paste it into the .wp-env.override.json and add your locally installed plugin. Copying the default plugins is needed as WP-ENV does not merge the values of the plugins.

{
	"plugins": [
		"./plugins/woocommerce",
		"https://downloads.wordpress.org/plugin/wp-crontrol.1.10.0.zip"
	]
}

Method 2 - Adding to the mappings

This method is simpler, but the plugin does not get activated on startup. You need to manually activate it yourself on the first startup.

{
	"mappings": {
		"wp-content/plugins/wp-crontrol": "../woocommerce"
	}
}

Accessing MySQL

The MySQL port can change when you restart your container.

You can get the current MySQL port from the output of wp-env start command.

1. Open your choice of MySQL tool.
2. Use the following values to access the MySQL container.

Name	Value
Host	127.0.0.1
Username	root
Password	password
Port	Port from the command

HOWTOs

How do I ssh into the container?

Run the following command to ssh into the container wp-env run wordpress /bin/bash

You can run a command in the container with the following syntax. You can find more about on the run command here

Syntax: wp-env run :container-type :linux-command