Skip to main content
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 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

1

Navigate to Your Plugin Directory

cd /path/to/your/wordpress-plugin
2

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.
3

Access Your WordPress Site

Once started, your WordPress site is available at: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:
1

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}
2

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

1

Fork and Clone

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

Add Upstream Remote

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

Install Dependencies

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

Build Gutenberg

For development with auto-rebuild on file changes:
npm run dev
For a one-time production build:
npm run build
5

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.
1

Install Local

Download and install Local from localwp.com
2

Create WordPress Site

Use Local’s interface to create a new WordPress site
3

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:
  1. EditorConfig - Automatically configures editor settings
  2. ESLint - JavaScript linting
  3. 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

  1. Ensure Docker Desktop is running
  2. Check for port conflicts on 8888 (WordPress) or 9000 (phpMyAdmin)
  3. Try destroying and recreating: wp-env destroy && wp-env start
Use a custom port:
WP_ENV_PORT=3333 wp-env start
Your site will be available at http://localhost:3333
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