Skip to main content
Before you can start developing custom blocks for the Gutenberg Block Editor, you need to set up your local development environment. This guide will walk you through the essential requirements and setup steps.

​
System requirements

Ensure your system meets these minimum requirements before proceeding with installation.
The Gutenberg Block Editor requires:
  • Node.js version 20.10.0 or higher
  • npm version 10.2.3 or higher
  • WordPress local development environment
  • Docker (optional, for wp-env)

​
Installation steps

1

Install Node.js and npm

Download and install Node.js from nodejs.org. This will also install npm, the Node package manager.Verify your installation by running:
node --version
npm --version
You should see version numbers matching or exceeding the system requirements above.
2

Set up a local WordPress environment

You have several options for running WordPress locally:The @wordpress/env package provides a simple way to set up a local WordPress environment using Docker.
npm install -g @wordpress/env

​
Option 2: Traditional local environment

You can also use traditional local development tools like:
If using wp-env, ensure Docker is installed and running on your machine before proceeding.
3

Install the Gutenberg plugin (optional)

To get the latest features and test bleeding-edge functionality, you can install the Gutenberg plugin:From WordPress admin:
  1. Navigate to Plugins → Add New in your WordPress dashboard
  2. Search for “Gutenberg”
  3. Click “Install Now” and then “Activate”
Or download directly:
The Gutenberg plugin is not required for block development. WordPress includes the block editor by default. The plugin provides access to the latest features before they’re merged into WordPress core.
4

Install build tools

The @wordpress/scripts package provides all the build tooling you need for block development:
npm install --save-dev @wordpress/scripts
This package includes webpack configuration, Babel presets, ESLint rules, and more—all pre-configured for WordPress block development.

​
Verify your installation

To verify everything is set up correctly, run the following commands: 
# Check Node.js version
node --version

# Check npm version
npm --version

# Check if wp-env is installed (if using wp-env)
wp-env --version

​
Development tools

While not required, these tools will enhance your development experience:

VS Code

The most popular code editor for JavaScript development with excellent WordPress extensions available.

Browser DevTools

Chrome or Firefox developer tools for debugging JavaScript and inspecting the DOM.

React Developer Tools

Browser extension for debugging React components used throughout the block editor.

Git

Version control system for tracking changes and collaborating with others.

​
Common setup commands

Here are some common commands you’ll use during development: 
# Install dependencies
npm install

# Start development mode with watch
npm start

# Build for production
npm run build

# Run linting
npm run lint:js

# Format code
npm run format

​
Troubleshooting

​
Docker issues with wp-env

If wp-env fails to start:
  • Ensure Docker Desktop is running
  • Check that ports 8888 and 8889 are not in use
  • Try wp-env clean all to reset the environment

​
Node version conflicts

If you need to manage multiple Node versions, consider using:

​
Build errors

If you encounter build errors:
  • Clear your node_modules folder and run npm install again
  • Ensure you’re using the correct Node and npm versions
  • Check that all dependencies are properly installed

​
Next steps

With your development environment set up, you’re ready to create your first block. Head over to the quickstart guide to build a working block in minutes.

Build docs developers (and LLMs) love

Get started for freeTalk to us