This guide is for setting up your local environment for JavaScript development for creating plugins and tools to extend WordPress and the block editor. If you are looking to contribute to Gutenberg project itself, see additional documentation in the Getting Started guide.
A development environment is a catch-all term for what you need setup on your computer to work. The three main pieces needed for our development environment are:
- Node/NPM Development Tools
- WordPress Development Site
- Code Editor
Here is a summary of the guide. See each section for additional details and explanations.
1. Install Node development tools
Download and install Node Version Manager (nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
Quit and restart terminal Install Node.js v18.
nvm install 18
2. WordPress Development Site
First download, install, and start Docker Desktop following the instructions for your OS.
- Install WordPress environment tool
npm -g install @wordpress/env
Start the environment from an existing plugin or theme directory, or a new working directory:
wp-env start
You will have a full WordPress site installed, navigate to: http://localhost:8888/ using your browser, log in to the WordPress dashboard at http://localhost:8888/wp-admin/ using Username "admin" and Password "password", without the quotes.
3. Code Editor
You can use any text editor to write code. For example, Visual Studio Code is a popular open-source editor. You can follow instructions on their site to install it for your OS.
The tools needed for development are Node and NPM. Nodejs is a runtime environment that allows running JavaScript outside of the browser. NPM is the Node Package Manager, it is used for installing dependencies and running scripts. The script npx is also installed with Nodejs—this script is used to run packages not yet installed—we will use npx to bootstrap a block.
The tools are used to convert the JavaScript we are going to write into a format that browsers can run. This is called transpiling or the build step.
For Mac and Linux, it is recommended to use the Node Version Manager (nvm). Using nvm to install node allows installing specific versions, plus installs locally in your home directory and avoids any global permission issues.
For Windows, or alternative installs, you can download a Nodejs installer directly from the main Node.js website, v18 is recommended. Installers are available for Windows and Mac, and binaries available for Linux. See Node.js site for additional installation methods.
Here are the quick instructions to install using nvm, see the full installation instructions for additional details.
Run the following on the command-line to install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bashNote: On macOS, the required developer tools are not installed by default, if not already installed you may be prompted to download the install.
After installing nvm, you need to use it to install Node.js, to install v18, run:
nvm install 18If there is an error running the above command, for example a common error that occurs is:
$ nvm install 18
zsh: command not found: nvmFirst, try quitting and restarting your terminal to pick up the installed config.
If restarting did not resolve the problem, you might need to create the default profile file.
On macOS Catalina, the default shell is zsh, to create the profile file type touch ~/.zshrc on the command-line. It is fine to run if the file already exists. Note, ~/ is a shortcut to your home directory. For Ubuntu, including WSL, the default profile is bash, use touch ~/.bashrc to create.
After creating the profile file, re-run the install command:
nvm install 18The important part after installing is being able to use them in your terminal. Open a terminal command-line and type node -v and npm -v to confirm they are installed.
> node -v
v18.14.2
> npm -v
9.6.0Your versions may not match exactly, that is fine. The minimum version for Node.js is >= 18 and for npm >= 9, using v18 will be supported until upgrade is required.
There are several ways to run WordPress locally on your own computer, or you could even develop on a cloud hosted computer, though this may be slower.
The WordPress wp-env package lets you set up a local WordPress environment for building and testing plugins and themes, without any additional configuration.
The wp-env tool uses Docker to create a virtual machine that runs the WordPress site. There are instructions available for installing Docker on Windows 10 Pro, other versions of Windows 10, macOS, and Linux. If using Ubuntu, see our additional notes for help installing Docker on Ubuntu.
After you have installed Docker, go ahead and install the wp-env tool. This command will install the tool globally, which means you can run it from any directory:
npm -g install @wordpress/envTo confirm it is installed and available, run:
wp-env --version
> 1.6.0The wp-env script is used to create a Docker WordPress environment. You can use this script to start an environment with your plugin activated by running it from the directory containing your plugin. For example if you are following the create block tutorial, this would be in the generated directory like so:
npx @wordpress/create-block starter-block
cd starter-block
wp-env startYou can access your environment in your browser at: http://localhost:8888/, the default username is admin and default password is password. For more information controlling the Docker environment see the @wordpress/env package readme.
When using the script while developing a single plugin, wp-env start can mount and activate the plugin automatically when run from the directory containing the plugin. Note: This also works for themes when run from the directory in which you are developing the theme.
If you run wp-env start from a directory that is not a plugin or theme, a generic WordPress environment will be created. The script will display the following warning, it is fine if this is your intention.
!! Warning: could not find a .wp-env.json configuration file and could not determine if 'DIR' is a WordPress installation, a plugin, or a theme.
You can use the .wp-env.json configuration file to create an environment that works with multiple plugins and/or themes. See the @wordpress/env package for additional details.
A common issue when running wp-env is Error while running docker-compose command.
- Check that Docker Desktop is started and running.
- Check Docker Desktop dashboard for logs, restart, or remove existing VMs.
If you see the error: Host is already in use by another container
- The container is already running, or another one is. You can stop an existing container running use
wp-env stopfrom the directory you started it. - If you do not remember the directory you started wp-env in, you can stop all containers with
docker stop $(docker ps -q). Please note, this will stop all containers, use caution with this command.
Docker is just one method to run a local WordPress environment. Block development and extending WordPress is done using normal plugins, so any WordPress environment can be used. Here are some alternatives that you can consider which do not require installing Docker.
-
Local - Local is a single application you download and install. You will need to know where the plugin directory is located after install. If you create a site called
mywptypically the plugin directory is installed at~\Local Sites\mywp\app\public\wp-content\plugins -
WampServer or MAMP environments, both are quite similar to Local, combining a web server, PHP, and database. However these tools are not WordPress specific, so if you are not already using them, Local might be an easier option.
-
Remote server - you can work on a remote server, most hosts provide a quick WordPress setup. However, this will require additional time thorughout development syncing to the server, or working directly on the remote server.
The important part is having a WordPress site installed, and know where and how to update files in the plugins directory.
Visual Studio Code is a popular code editor for JavaScript development. It works quite well across the three major platforms (Windows, Linux, and Mac), it is open-source and actively maintained by Microsoft. Plus Visual Studio Code has a vibrant community providing plugins and extensions; it is becoming the defacto standard for web development.
Alternative editors include Sublime Text that is also available across platforms, though is a commercial product; or other free alternatives include Vim, Atom, and Notepad++ all support standard JavaScript style development.
You can use any editor you're comfortable with, it is more a personal preference. The development setup for WordPress block editor is a common JavaScript environment and most editors have plugins and support. The key is having a way to open, edit, and save text files.
Here are a few instructions if you need to start over, or want to remove what was installed.
- If you just want to reset and clean the WordPress database:
wp-env clean all
- To remove the local environment completely for a specific project:
wp-env destroy
- To completely uninstall wp-env tool:
npm -g uninstall @wordpress/env
- To uninstall Docker, or Visual Studio Code use your OS method to remove packages. For example, on Windows run "Add or remove programs". You can additionally uninstall from the Docker Desktop app, click the bug icon at the top to switch to this Troubleshoot screen. Click Uninstall or remove.
To uninstall Node/NVM, delete the NVM directory, this is typically installed at $HOME/.nvm, delete using
rm -rf "$HOME/.nvm"
If this does not work and the $NVM_DIR environment variable is set you can remove using rm -rf "$NVM_DIR"
To clean up any installed JavaScript packages remove the global .npm directory at $HOME/.npm,
rm -rf "$HOME/.npm"
Just as you confirmed the installation worked, you can confirm the uninstall worked. First quit and restart terminal and then try to run npm -v, node -v, and nvm -v you should then see a "command not found" error in the terminal.