Skip to main content

Yoast SEO development setup

This page describes the process of how we set up development environments at Yoast.


These instructions assume you're working with Mac OSX and PHP 7.4+.

Getting started

Before you start contributing to the Yoast plugins, ensure you've checked out our development tools page which lists the various tools that need to be used (unless otherwise noted).

Organizing your projects

Generally speaking, we advise people to create a ~/Projects/Yoast folder to keep all things together.


Don't create a Yoast folder in ~/Documents, ~/Desktop or ~/Downloads as this will likely cause errors when using the plugin-development-docker.

After creating this folder, you have two flavors:

  • Clone plugins on an environment-by-environment basis, which allows you to have various versions of the same plugin on your system, without them (possibly) conflicting.
  • Clone all plugins into a single directory and symlink them to the development environments. This results in the same version (branch) running across all development environments that were linked.

Symlinking is generally preferable, as there's a lower chance of messing things up, as there is a single source of truth.

Cloning plugins on an environment-by-environment basis

If you use Local as your development environment of choice, you can follow these steps to clone the plugins to your Local site's plugins directory.

On Mac

  • Clone the plugin(s) you want to develop to ~/Applications/Local\ Sites/<site-name>/app/public/wp-contents/plugins, where <site-name> is the name of the Local site you want to use for plugin development.

Cloning plugins into a single directory and symlinking them

If you use Local as your development environment of choice, you can follow these steps to clone the plugins to a separate directory and symlink them to your Local site's plugin directory.

On Mac

  • Clone the plugins that you want to develop to a single folder of choice.
  • Symlink this folder to the ~/Applications/Local\ Sites/<site-name>/app/public/wp-contents/plugins folder, where <site-name> is the name of the Local site you want to use for plugin development.

Set up PHPUnit

Enabling PHPUnit in PhpStorm

The setup in PhpStorm can be completed by following the next steps:

  • Under the Run menu in PhpStorm, go to Edit configurations.
  • In the following window, press the + in the left corner and choose PHPUnit in the options.
  • Select the option: Defined in the configuration file and check the checkbox for Use alternative configuration file.
  • Behind the checkbox, enter the full path to the phpunit.xml.dist file. This file is located in the plugin directory. If the repository contains a phpunit.xml file, use that one instead. (i.e wordpress-seo has two types of tests. Use phpunit-integration.xml.dist for the 'old' integration tests, and phpunit.xml.dist for the BrainMonkey tests.)
  • Now you've entered the path, press the icon on the far right. This will bring you to the Test frameworks window.
  • Press the plus icon and select the first option: PHPUnit Local. Select Use Composer autoloader, which will autofill the Path to script to a path that ends with /vendor/autoload.php. This selection will prompt PhpStorm to use the version as retrieved via Composer.
  • Finally, when you return to the Run/Debug configurations window, there might be an error message at the bottom. Press the Fix button next to it and select PHP as your CLI interpreter. Apply and done!

Configuring PHPUnit to work with WordPress and the plugins

In order to ensure that unit tests can properly run, you need to add the following two constants:

  • WP_DEVELOP_DIR - Refers to the cloned repository of wordpress-develop, as it's located on your system.
  • WP_PLUGIN_DIR - Refers to the directory where the WordPress plugins are located.


WP_DEVELOP_DIR=/Users/<your name>/Documents/Development/wordpress-develop/
WP_PLUGIN_DIR=/Users/<your name>/Documents/Development/plugin-development-docker/plugins

Note the trailing slash in WP_DEVELOP_DIR and the absence of it in WP_PLUGIN_DIR.


If you have WP_DEVELOP_DIR and WP_PLUGIN_DIR as environment variables, you can skip the following section.

Configure your PHPUnit configuration in PhpStorm by going to Edit Configurations... -> PHPUnit and ensure it looks similar to the following screenshot:

Running multisite tests

Some of our plugins contain tests that are only run on multisite. To run those tests, select your PHPUnit configuration and add the WP_MULTISITE flag with value 1 in the command line section of the settings.

Installing the plugins

To have the complete set of Yoast plugins, clone the following repositories in your /plugins/ folder.

Yoast SEO with the addons:

For each of these add-ons, run composer install and yarn in the respective directories to make sure all dependencies are installed.

Additional plugins:

All our publicly accessible repositories can be found on GitHub

Enable indexable indexation

Working on JavaScript used in the plugins

If you're developing within the JavaScript code that is part of one of the plugins, you need to ensure that the code is also available in your WordPress environment. This can be achieved by using the following steps:

  • Run yarn to install dependencies.
  • Run grunt build:js to build JavaScript manually.
  • Run grunt shell:webpack-watch (Free) or grunt webpack:watch (Premium) to watch and build JavaScript automatically.

If your pull-request requires a specific branch from the monorepo, please ensure that you create a branch on the monorepo with the exact same name as the branch on the plugin's repository. This ensures that Travis uses the correct branches when building.

Working on standalone JavaScript

If you're planning on working on the JavaScript code, outside of a WordPress environment, you can follow the instructions in the readme of the monorepo, which includes all the information you'll need to get the JavaScript side of things up and running.

A list if useful commands is also available.

Generating fake data for testing

You can use Yoast WP CLI Faker to generate fake data like posts, terms and users.

Now what?

After you've cloned the repositories, you can navigate to basic.wordpress.test in your browser to see the development environment. Open the plugin directory in your IDE and you should be ready to develop!