WooCommerce Email Editor Development

This skill provides guidance for developing the WooCommerce block email editor.

When to Use This Skill

Invoke this skill when:

• Setting up local development for the email editor
• Working on email templates or transactional emails
• Modifying the email editor PHP or JS packages
• Testing email sending functionality

Development Environment Setup

1. Start WooCommerce wp-env

pnpm --filter=@woocommerce/plugin-woocommerce -- wp-env start

Site runs at http://localhost:8888 by default. If port 8888 is unavailable, wp-env assigns a different port. Check the startup output or run wp-env info to see your actual URL.

2. Start the watcher

Watches and builds admin JS files (including the email editor JS package) and syncs Email Editor PHP package changes:

pnpm --filter=@woocommerce/plugin-woocommerce watch:build:admin

3. Enable the block email editor feature

Visit http://localhost:8888/wp-admin/admin.php?page=wc-settings&tab=advanced&section=features and enable the block email editor.

4. Edit transactional emails

Visit http://localhost:8888/wp-admin/admin.php?page=wc-settings&tab=email

Email Testing with Mailpit

To test email sending locally, use Mailpit as a local SMTP server.

Configure SMTP

Add to plugins/woocommerce/.wp-env.override.json:

{
    "lifecycleScripts": {
        "afterStart": "./tests/e2e-pw/bin/test-env-setup.sh && wp-env run cli wp plugin install wp-mail-smtp --activate"
    },
    "config": {
        "WPMS_ON": true,
        "WPMS_MAILER": "smtp",
        "WPMS_SMTP_HOST": "host.docker.internal",
        "WPMS_SMTP_PORT": "1025",
        "WPMS_SMTP_AUTH": false,
        "WPMS_SMTP_SECURE": ""
    }
}

Start Mailpit

docker run --rm --name=mailpit -p 1025:1025 -p 8025:8025 -d axllent/mailpit

Or if the container already exists:

docker start mailpit

View emails

Open http://localhost:8025 to see captured emails.

Restart wp-env

After creating or modifying .wp-env.override.json, restart the environment:

pnpm --filter=@woocommerce/plugin-woocommerce -- wp-env start --update

Key Paths

Building the Email Editor Package

To rebuild the JS package after changes:

pnpm --filter=@woocommerce/email-editor build

Testing the PHP Package

Run tests from the packages/php/email-editor/ directory.

Setup

cd packages/php/email-editor
wp-env start
composer dump-autoload

Run integration tests

wp-env run tests-cli --env-cwd=wp-content/plugins/email-editor ./vendor/bin/phpunit --configuration phpunit-integration.xml.dist

Run a specific test

wp-env run tests-cli --env-cwd=wp-content/plugins/email-editor ./vendor/bin/phpunit --configuration phpunit-integration.xml.dist --filter Table_Test

Linting the PHP Package

Run from the packages/php/email-editor/ directory.

PHPStan

cd tasks/phpstan && ./run-phpstan.sh

For PHP 7 compatibility:

cd tasks/phpstan && ./run-phpstan.sh php7

PHPCS

composer run phpcs