Development Environment Setup

This guide walks you through setting up a professional development environment for building custom WordPress blocks and contributing to the Gutenberg project.

Prerequisites

You’ll need to install these tools before setting up your development environment:

Node.js and npm

Gutenberg requires Node.js v20 and npm v10. We recommend using Node Version Manager (nvm) for easy version management.

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

# Install Node.js v20
nvm install 20
nvm use 20

# Verify installation
node --version  # Should show v20.x.x
npm --version   # Should show v10.x.x

Always use the Active LTS version of Node.js for the best compatibility. Check the Node.js release schedule for current versions.

Git

Gutenberg uses Git for version control. Install Git if you haven’t already:

brew install git

Docker Desktop

Docker powers the wp-env local WordPress environment. Install Docker Desktop for your platform:

Windows: Docker Desktop for Windows (WSL2 backend recommended)
macOS: Docker Desktop for Mac
Linux: Docker Desktop for Linux

Windows 10 Home users should follow the WSL2 installation instructions for the best experience.

Setting Up wp-env

wp-env is the official WordPress local development environment tool. It creates a Docker-based WordPress instance with zero configuration.

Install wp-env Globally

npm install -g @wordpress/env

Quick Start with wp-env

Navigate to Your Plugin Directory

cd /path/to/your/wordpress-plugin

Start the Environment

Ensure Docker is running, then start wp-env:

wp-env start

This command:

Downloads the latest WordPress Docker image
Creates a MySQL database
Installs and activates your plugin
Mounts your plugin code as a Docker volume

First-time setup may take several minutes as Docker downloads the required images.

Access Your WordPress Site

Once started, your WordPress site is available at:

WordPress site: http://localhost:8888
Admin dashboard: http://localhost:8888/wp-admin/
Credentials: Username admin, Password password

Your plugin is automatically installed and activated.

Managing wp-env

Essential Commands

wp-env start

Expected Output

When wp-env start completes successfully, you’ll see:

WordPress development site started at http://localhost:8888/
MySQL is listening on port 51220

 ✔ Done! (in 261s 898ms)

Accessing the Database

Using phpMyAdmin

phpMyAdmin is available by default at http://localhost:9000/

Using External Database Tools

To connect with tools like Sequel Ace or MySQL Workbench:

Find the MySQL Port

Start wp-env and note the MySQL port number in the output:

wp-env start

Look for: MySQL is listening on port {MYSQL_PORT_NUMBER}

Connect with These Credentials

Host: 127.0.0.1
Username: root
Password: password
Database: wordpress
Port: {MYSQL_PORT_NUMBER}

The MySQL port changes each time wp-env restarts. You’ll need to update your connection settings if you restart the environment.

Setting Up for Gutenberg Development

If you’re contributing to Gutenberg itself, follow these additional steps:

Clone the Gutenberg Repository

Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_GITHUB_USERNAME/gutenberg.git
cd gutenberg

Add Upstream Remote

git remote add upstream https://github.com/WordPress/gutenberg.git

Install Dependencies

npm install

This requires Python to be installed and available in your system PATH.

Build Gutenberg

For development with auto-rebuild on file changes:

npm run dev

For a one-time production build:

npm run build

Start WordPress Environment

npm run wp-env start

This uses the wp-env configuration specific to the Gutenberg project (defined in .wp-env.json).

Gutenberg-Specific Environment

The Gutenberg project includes a custom .wp-env.json configuration:

.wp-env.json

{
    "core": "WordPress/WordPress",
    "plugins": [ "." ],
    "themes": [ "./test/emptytheme" ],
    "phpmyadminPort": 9000
}

This configuration:

Mounts Gutenberg as a plugin
Includes test themes
Configures phpMyAdmin on port 9000

Alternative Development Environments

If you prefer not to use Docker, you can use these alternatives:

Local by Flywheel

Local provides a GUI-based local WordPress environment.

Install Local

Download and install Local from localwp.com

Create WordPress Site

Use Local’s interface to create a new WordPress site

Add Your Plugin

Symlink or copy your plugin to the site’s wp-content/plugins/ directory:

ln -s /path/to/your-plugin /path/to/local-site/app/public/wp-content/plugins/your-plugin

MAMP

MAMP is a classic Apache/MySQL/PHP stack for local development.

When using MAMP, you may need to disable OPCache for PHP file changes to reflect immediately. Go to MAMP > Preferences > PHP and set Cache to off.

Development Tools Configuration

Configure your editor for the best development experience:

Visual Studio Code

Install these recommended extensions:

EditorConfig - Automatically configures editor settings
ESLint - JavaScript linting
Prettier - Code formatting

VS Code Settings

Add to your .vscode/settings.json:

.vscode/settings.json

{
    "editor.codeActionsOnSave": {
        "source.fixAll.eslint": "explicit"
    },
    "[javascript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "editor.formatOnSave": true
    },
    "[markdown]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "editor.formatOnSave": true
    }
}

Running Tests

Gutenberg includes comprehensive test suites:

npm run test:unit

PHP and E2E tests require wp-env to be running. Start it with npm run wp-env start before running these tests.

Troubleshooting

Docker Issues

wp-env won't start

Ensure Docker Desktop is running
Check for port conflicts on 8888 (WordPress) or 9000 (phpMyAdmin)
Try destroying and recreating: wp-env destroy && wp-env start

Port 8888 is already in use

Use a custom port:

WP_ENV_PORT=3333 wp-env start

Your site will be available at http://localhost:3333

Permission errors on Linux

Add your user to the Docker group:

sudo usermod -aG docker $USER

Then log out and log back in.

For more troubleshooting help, see the wp-env troubleshooting guide.

Next Steps

Create Your First Block

Build a custom block from scratch

Git Workflow

Learn the Git workflow for contributing

Overview

Getting Started

Core Concepts

Block Development

Advanced Guides

Prerequisites

Node.js and npm

Git

Docker Desktop

Setting Up wp-env

Install wp-env Globally

Quick Start with wp-env

Managing wp-env

Essential Commands

Expected Output

Accessing the Database

Using phpMyAdmin

Using External Database Tools

Setting Up for Gutenberg Development

Clone the Gutenberg Repository

Gutenberg-Specific Environment

Alternative Development Environments

Local by Flywheel

MAMP

Development Tools Configuration

Visual Studio Code

VS Code Settings

Running Tests

Troubleshooting

Docker Issues

Next Steps

Create Your First Block

Git Workflow

Build docs developers (and LLMs) love

Overview

Getting Started

Core Concepts

Block Development

Advanced Guides

​Prerequisites

​Node.js and npm

​Git

​Docker Desktop

​Setting Up wp-env

​Install wp-env Globally

​Quick Start with wp-env

​Managing wp-env

​Essential Commands

​Expected Output

​Accessing the Database

​Using phpMyAdmin

​Using External Database Tools

​Setting Up for Gutenberg Development

​Clone the Gutenberg Repository

​Gutenberg-Specific Environment

​Alternative Development Environments

​Local by Flywheel

​MAMP

​Development Tools Configuration

​Visual Studio Code

​VS Code Settings

​Running Tests

​Troubleshooting

​Docker Issues

​Next Steps

Create Your First Block

Git Workflow

Build docs developers (and LLMs) love

Prerequisites

Node.js and npm

Git

Docker Desktop

Setting Up wp-env

Install wp-env Globally

Quick Start with wp-env

Managing wp-env

Essential Commands

Expected Output

Accessing the Database

Using phpMyAdmin

Using External Database Tools

Setting Up for Gutenberg Development

Clone the Gutenberg Repository

Gutenberg-Specific Environment

Alternative Development Environments

Local by Flywheel

MAMP

Development Tools Configuration

Visual Studio Code

VS Code Settings

Running Tests

Troubleshooting

Docker Issues

Next Steps