Developer.WordPress.org Theme

Development

Prerequisites

All commands below need to be executed as non-root user.

• Docker
• PHP >= 7.4.0 with extensions: xml, mysql, mbstring, curl, zip, intl
• Node/npm >= 18
• Yarn
• Composer
• SVN

How to install the prerequisites

Setup

0. Update composer dependencies

   composer update

   If you never set up a Github token for composer, you might get a rate-limit error. In this case, just go to the link provided in the error report to generate a GitHub token (no specific permissions needed) and copy-paste the obtained token into the terminal prompt.

1. Set up repo dependencies.

   yarn setup:tools

2. Build the assets. If there's anything that needs setting up.

   yarn build

3. Start the local environment.

   yarn wp-env start

   This step should take a couple of minutes to download WordPress, then install and configure it. If it does not perform all those actions, you can retry with:

   yarn wp-env destroy
   yarn wp-env start

   If this step worked properly, you should be able to access a new WordPress website at localhost:8888. The website should be ready to use (ie. WordPress already installed).

4. Run the setup script (do it only once).

   yarn setup

Note: if this is the first activation of the wp-env, there is a conflict between plugins: "Posts 2 posts" and WP Parser, preventing the later to activate. Manually log into the admin panel, deactivate "Posts 2 Posts" manually, activate WP Parser and then re-activate "Posts 2 Posts". Issue tracked here: WordPress#523

1. Visit site at localhost:8888.

2. Log in with username admin and password password.

WP Rocket

• Update WP Rocket and Parse WP Rocket

  yarn parse

• Update WP Rocket

  yarn update:wprocket

• Delete all developers docs (posts/terms) created.

  yarn parse:reset

Environment management

These must be run in the project's root folder, not in theme/plugin subfolders.

• Stop the environment.

  yarn wp-env stop

• Restart the environment.

  yarn wp-env start

• Open a shell inside the docker container.

  yarn wp-env run wordpress bash

• Run wp-cli commands. Keep the wp-cli command in quotes so that the flags are passed correctly.

  yarn wp-env run cli "post list --post_status=publish"

• Update composer dependencies and sync any repo-tools changes.

  yarn update:tools

• Watch for SCSS changes and rebuild the CSS as needed.

  yarn start:theme

• Parse the code reference again. This is run as part of the project setup.

  yarn parse

Asset management

• Build assets once: yarn build:theme
• Watch assets and build on changes: yarn start:theme

Install prerequisites

Yarn

curl -o- -L https://yarnpkg.com/install.sh | bash
yarn --version

Subversion

apt install subversion

NVM

Install NVM

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

Node

Install Node 18

nvm install 18
node -v

PHP

Check PHP version and switch PHP version to PHP7.4 if it is already installed:

php -v
sudo update-alternatives --config php

Install PHP 7.4 and required/basic extensions:

apt install php7.4 php7.4-cli php7.4-xml php7.4-mysql php7.4-mbstring php7.4-curl php7.4-zip php7.4-intl php7.4-gd php7.4-bcmath php7.4-imagick

Switch PHP version to PHP7.4:

sudo update-alternatives --set php /usr/bin/php7.4

FAQ

FAQ Issue with docker Could not connect to Docker

docker ps

Getting permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker

Solution:

unset DOCKER_HOST
sudo usermod -aG docker $USER

Then close and reopen terminal:

docker ps
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES