Skip to content

05 Local Development Guide

Jump to bottom
JuanMa edited this page May 10, 2024 · 1 revision

This document aims to provide as much context as possible to aid in the development of the examples in this monorepo.

Please refer to the Getting Started section of the Wiki for a general-purpose guide on getting started. The rest of this document will assume that you've installed all the prerequisites and setup described there.

WordPress Local Development Environment

This project recommends using wp-env to create a local development environment.

# Make sure you are in the working directory of the plugin you are interested in setting up the environment for
cd plugins/minimal-block-ca6eda
# Start will create the environment if necessary or start an existing one
pnpm -- wp-env start
# Stop will, well, stop the environment
pnpm -- wp-env stop
# Destroy will remove all of the environment's files.
pnpm -- wp-env destroy

Note

See "Quick and easy local WordPress development with wp-env" and wp-env package reference to learn more about wp-env

You can also do npm run env:start from the root to run a WordPress environment with the plugins at .wp-env.json.

Edit the property "plugins" at .wp-env.json to include just the examples you're interested in. To apply these changes after having started your instance, run npm run env:update from the root folder

Build process

ESNext and JSX are the recommended syntaxes for code blocks, but they're not directly supported by the majority of browsers. Because of this, most of the examples of this repo need to run a Build process to get the final version ready to use.

There are some examples in this repo that don't use ESNext or JSX Syntax, so they don't need to run any build process. These examples are labeled with the tag NO-BUILD.

Launch npm run build to run the build process:

  • from each plugin folder → to run the build process only for that plugin
  • from the root → to run the build process for ALL the plugins of the repo

Repo Commands

Our repository uses pnpm to manage dependencies of examples and run commands on them collectively.

When using pnpm run {command} without any options, it will execute that command against every project in the repository.

Here are some examples of the ways you can use pnpm commands to run scripts on all the packages of the repo:

# Build of all examples
pnpm run build

# Start all the examples (build and watch changes in any plugin)
pnpm run start

# Run tests of packages with tests
pnpm run test:e2e

Dependencies

This tool optimizes the dependencies installation for all the examples, so any installation of dependencies in this repo should be done by pnpm

Any time you want to install (or reinstall dependencies) for the examples, you should from the root of the project:

pnpm install

Scripts

There is a set of predefined scripts you can run from the root with npm run {script} to manage the examples in this repo

You can check the scripts available by doing npm run from the root or by checking the scripts property of package.json

Tool Filtering

If you are interested in running a specific command against a single plugin, package, or tool, you can do so with the --filter flag. This flag supports the "name" option in package.json files, paths, and globs.

Examples

Here are some examples of the ways you can use pnpm commands:

# Start minimal-block-ca6eda
pnpm run --filter='*ca6eda' start

# Build minimal-block-ca6eda
pnpm run --filter='*ca6eda' build

# Run tests of editable-block-1b8c51 package
pnpm run --filter='*1b8c51' test:e2e

# Run tests of all editable-block-1b8c51
pnpm run --filter='*1b8c51' test:e2e

# Build everything that has changed since the last commit
pnpm run --filter='[HEAD^1]' build

Coding Standards

The examples in this repository follow the WordPress Coding Standards and any new examples or updates to existing ones are required to adhere to these standards as well.

To make this process as seamless as possible, this repository provides all of the tools needed to ensure these standards are met:

Local Development

When developing locally, the following commands are available to manually lint PHP, JS, and CSS, respectively:

  • npm run lint:php
  • npm run lint:js
  • npm run lint:css

Additionally, there is a pre-commit hook in place provided by Husky that will lint any code to be committed automatically and block commits until the tests are passed.

Formatting commands

Some linting errors are fixable using automated tools. You can run the following commands to attempt to fix them. Note that some errors may need to be manually fixed:

  • npm run format:php - will attempt to fix linting errors in PHP using phpcbf.

Remote

When a new PR is created or merged into trunk, there is an action in place to lint all the code to ensure that there are no issues.

Clone this wiki locally