This monorepo contains all the code for the ionos-wordpress project.

It lets developers maintain all our IONOS WordPress hosting plugins in one place.

Philosophy

• Self contained

  The repository contains all the code, configuration, and tools needed to maintain plugins specific to IONOS WordPress Hosting.

  Even the tooling and its configuration are integrated in the repository. The repository declares tools as dependencies, or it runs them in containers.

  After you check out the repository, everything is in its place and you can start work immediately. You must install only a minimal set of Requirements on your machine.

• Cross platform

  The repository is designed to work on major operating systems. It uses a containerized approach to run native tools and services.

• Mono structure

  The repository is organized as Monorepo to maintain various sub projects in a single place.

  This lets us share code and configuration between the sub projects. It also lets us maintain a single version for all of them.

• Local first

  The repository is designed to work locally first. It uses a containerized approach to run native tools and services.

  This lets you work on the code and configuration locally. You can test it in a local environment before you push it to a remote repository.

Development

The default password for the dev WordPress container is defined in environment variable WP_PASSWORD. The environment variable is defined in .env.

The repository contains all the code, configuration, and tools needed to maintain artifacts specific to IONOS WordPress Hosting.

The repository gives

• automatic provisioning of a Docker-based WordPress dev container (wordpress-alpine, see packages/docker/wordpress-alpine/) with WordPress autocompletion and PHP debugging (Xdebug) enabled out of the box

• vscode configuration and settings so that all required plugins and settings are automatically installed and configured

Branches & Naming

The repository branching is inspired by git flow. There is a development branch. Feature branches split from this branch and later merge back into it. To easily identify the kind of change, use one of the following prefixes for your feature branches:

• feature/
• bugfix/
• docs/
• chore/

If there is a Jira ticket that this branch implements, append it to the end of your branch name like so: "feature/add-awesome-button-GPHWPP-123"

Directory layout

• The top level directory contains configuration files

  • pnpm-workspace.yaml configures where pnpm finds sub packages, such as WordPress plugins

  • .npmrc configures pnpm behavior, such as the Node.js version pnpm supplies automatically and the package cache location.

  • pnpm-lock.yaml is the lock file generated by pnpm.

  • .editorconfig configures the code style for the repository. Various editors and IDEs use this file to enforce the code style.

  • See Customization for details about the .env, .secrets, and .env.local files.

• Directory packages/ contains all the sub projects sorted by category.

  • packages/wp-plugin/ contains WordPress plugin sub projects

  • packages/npm/ contains npm package sub projects

  • packages/docker/ contains docker image sub projects

  • packages/docs/ contains documentation sub projects

  Not all of the package categories are required to be present in the repository. You can remove or create category directories as needed (i.e. if the first docker sub project is required, create packages/docker and place the docker sub project inside).

Important

Why are the sub projects sorted into category directories? Different types of artifacts have different requirements and require a different build/release workflow. By sorting the sub projects into category directories, we give each category one unified build and release workflow automatically.

Requirements

• vscode

  You do not strictly need vscode, but it makes work with the repository much easier.

  You can use DevContainer with other IDEs, like PHPStorm, but this repository supports only vscode for now.

  • Install the ms-vscode-remote.remote-containers extension to use the DevContainer feature.

• a modern docker version (including docker compose sub command)

All other tools are in a DevContainer. This container gives a unified development experience across all platforms.

Tip

vscode automatically starts the DevContainer when you open the repository in vscode. Our DevContainer gives you tools like pnpm, bash, and other native tools needed to maintain the software artifacts in this repository.

Toolchain

The project-specific DevContainer automatically supplies the software described here.

• We use pnpm as the package manager instead of npm, because of its excellent monorepo support. It also:

  • is much faster than npm and yarn

  • caches once downloaded packages and reuses them across projects

  • uses hard links to save disk space

  • computes sub project dependencies for free

  • manages NodeJS provisioning automatically

• bash, jq and friends

  We need shell and some shell commands to implement workflows and scripts.

Setup

• checkout the repository

  • switch to branch develop if you want to work on the latest development version : git switch develop

• open the repository in vscode

vscode will now install the extensions and automatically start the DevContainer. This gives you the whole toolchain.

• run pnpm install to install dependencies

Commands

All commands are declared in the scripts section of the root package.json file.

You can run each command as a script, using pnpm run <command> or the shorter pnpm <command>.

To get a list of commands, you can run pnpm run.

The commands are shell scripts in the ./scripts/ directory.

The command scripts in ./scripts/ also contain some advanced usage examples.

Tip

Some commands require you to run other commands first. Because of the limits of package scripts, we cannot declare dependencies between scripts. So we rely on you, the developer, to run the commands in the correct order. Dependency-aware tools like make would solve this issue, but we skip them for now, to keep the toolchain simple to understand.

• pnpm start : starts the persistent wordpress-alpine dev container. It builds the Docker image first, if needed. It dynamically bind-mounts all WordPress plugins, themes, and mu-plugins declared in the repository.

  The wordpress-alpine image includes Xdebug, enabled by default. No separate flag is needed. Xdebug attaches on every request. It connects back to the IDE at host.docker.internal:9003 (mapped to the docker host through --add-host). So, to hit breakpoints, just start the generated ionos-wordpress launch configuration in vscode.

  You can run pnpm start repeatedly. It is idempotent as long as the container already exists. Run pnpm destroy first if you need volume/env changes to take effect on the next pnpm start.

  Exception: pnpm start automatically detects a changed WORDPRESS_VERSION. In this case, it recreates the container for you. This action wipes ${MNT_HOME}/dev, meaning the database, uploads, and wp-config.php. It does not silently continue to serve the original core.

  .vscode/launch.json (the Xdebug launch configuration) is regenerated on every pnpm start. See vscode.

• pnpm stop : stops the wordpress-alpine dev container.

• pnpm destroy : removes the wordpress-alpine dev container and its per-stack overlay data (the shared, version-keyed WordPress core cache survives).

• pnpm logs : tails the dev container's logs (Apache/MariaDB/debug.log).

• pnpm enter : opens an interactive shell in the dev container.

• pnpm cli : runs a wp-cli command inside the dev container, e.g. pnpm cli plugin list.

• pnpm build : builds all sub projects of the monorepo.

  It builds all WordPress plugins, themes, and more.

• pnpm watch : builds all sub projects of the monorepo, and rebuilds them whenever a sub project file changes.

• pnpm changeset : gives access to the changeset tool.

  The command is a wrapper around the changeset tool to give a unified interface to manage changesets.

  Changesets are a way to version and release multiple software artifacts in a monorepo. They also give a changelog for end users.

  See Changeset for more details of the changeset workflow.

Advanced commands

• pnpm clean : cleans up resources generated by the build process.

  The command is configured to be interactive (see .env) so you can selectively decide which resources to clean up.

• pnpm distclean : cleans up ANY generated Monorepo resources (like ./node_modules and so on).

  This command reverts the project repository to a clean state, as if you just checked out the repository. The only things it keeps are

  • files that are under version control
  • .code-workspace file
  • .env.local file
  • .secrets file

  The command is configured to be interactive (see .env) so you can selectively decide which resources to clean up.

  After you delete all dependencies with pnpm distclean, you must run pnpm install manually before you call any other command.

  [!TIP] To keep more files automatically, add them to the GIT_CLEAN_OPTS variable in the .env or .env.local file.

• pnpm update-dependencies : lets you update the dependencies of the monorepo.

  The command shows you all dependencies that can be updated, and lets you decide which to update.

  Example usage : pnpm update-dependencies updates all dependencies within the ranges in package.json. pnpm update-dependencies --latest updates all dependencies to their latest versions.

Configuration

The project supports many ways to configure its settings.

Environment

• .env : contains the global configuration for the project.

  This file is under version control and contains the default configuration for the project.

  This file should not contain sensitive data like credentials or security tokens.

  Bash sources .env, so you can even declare and export bash functions here.

• .env.local : an optional environment configuration file for individual developer settings.

  You can use this file to override settings from .env, or to add individual settings.

  Bash sources .env.local, so you can even declare and export bash functions here.

  This file should not contain sensitive data like credentials or security tokens.

  It is not under version control.

  You can use .env.local.example as a template.

• .secrets is an optional file. You can use it to supply secret settings, like security tokens and credentials.

  It is not under version control.

  You can use .env.local.example as a template.

  Bash sources .env.local, so you can even declare and export bash functions here.

  [!CAUTION] scripts/start.sh forwards only a fixed allowlist of variables from .env, .secrets, and .env.local into the dev container (WORDPRESS_VERSION, WP_PASSWORD, HTTP_PORT, AFTER_START, HOST_UID, HOST_GID). Any other environment variable is only visible to the host-side scripts, not inside the container.

vscode

• .vscode/launch.json contains the Xdebug launch configuration for vscode

  packages/docker/wordpress-alpine/scripts/_generate-vscode-launch.sh generates this file on every pnpm start. So its path mappings always match the plugins, mu-plugins, and themes currently bind-mounted into the wordpress-alpine container (plus the phpunit mappings used by pnpm test:php).

  The file is machine-generated and not under version control. Do not edit it. Additional launch configurations belong in a *.code-workspace file.

• ./vscode/settings.json contains settings for vscode and vscode extensions.

  The @wordpress/env environment generates it on every start.

  The file is not under version control.

• ./vscode/extensions.json contains recommended extensions for vscode used by this project.

• *.code-workspace files are optional configuration files for vscode.

  A workspace file may contain settings, launch configuration and recommended plugins to install for the workspace. When used, it extends or overrides the default vscode settings for the Monorepo.

  Create a workspace file to configure vscode to your individual needs.

  Workspace files are not under version control.

Workflows

Changeset

Changesets are a way to version and release multiple software artifacts in a monorepo. They also give a changelog for end users, automatically.

Changesets do not harm how you work with Git. The changeset process is mostly independent of the Git workflow.

Create a feature

Whenever you start work on a new feature, a breaking change, or anything else worth noting in the changelog, you should create a new changeset entry :

pnpm changeset add

This command creates a new changeset markdown file in the ./changeset/ directory.

This file contains a human-readable description of the changeset, in markdown format. This description goes into the changelog when you create a new release with changeset.

The frontmatter section of this file notes which sub projects in the monorepo this changeset affects. It also notes the type of change: major, minor, or patch.

The changeset file stays under version control until the release. After you create the release, changesets merges the file into the affected changelog files and removes it from the changeset directory.

Git

The project uses git hooks at various stages.

For example, the pre-push hook automatically lints the code before push. It aborts the push if the lint fails. You must enable this with the environment variable LINT_ON_PUSH (see ./.env.local).

Git hooks are in the ./.githooks directory.

The pnpm install command automatically installs the hooks.

Tip

If you want to disable Git hooks, add --no-verify to the git command. Example : git commit --no-verify

Workflows

CI/CD

The CI/CD pipeline also uses this repository's DevContainer. This container gives exactly the same development environment for local development, CI/CD, and release.