Skip to main content
When developing for the Block Editor, you will need Node.js development tools along with a code editor and a local WordPress environment. Node.js (node) is an open-source runtime environment that allows you to execute JavaScript code from the terminal (also known as a command-line interface, CLI, or shell). Installing node will automatically include the Node Package Manager (npm) and the Node Package eXecute (npx), two tools you will frequently use in block and plugin development.

​
Node.js Tools

​
npm - Node Package Manager

Node Package Manager (npm) serves multiple purposes, including dependency management and script execution. It’s the recommended package manager and is extensively featured in all documentation. Common npm commands:
  • npm install - Install dependencies from package.json
  • npm install <package> - Install a specific package
  • npm run <script> - Run a script defined in package.json

​
npx - Node Package Execute

The Node Package eXecute (npx) tool is used to run commands from packages without installing them globally and is commonly used when scaffolding blocks with the create-block package. Example:

​
Installation on Mac and Linux

It’s recommended that you use Node Version Manager (nvm) to install Node.js. This allows you to install and manage specific versions of node, which are installed locally in your home directory, avoiding any global permission issues.

​
Managing Node Versions with nvm

If needed, you can install specific versions of node. For example, install version 18 by running:
Switch between different versions by running:
Some projects, like Gutenberg, include an .nvmrc file which specifies the version of node that should be used. In this case, running nvm use will automatically select the correct version. If the version is not yet installed, you will get an error that tells you what version needs to be added. Run:

​
Installation on Windows

You can download a Node.js installer directly from the main Node.js website. The latest version is recommended. Installers are available for Windows and Mac, and binaries are available for Linux.
Microsoft also provides a detailed guide on how to install nvm and Node.js on Windows and WSL.

​
Package Managers

While npm is the default and recommended package manager, you may encounter projects using alternatives:

​
Troubleshooting

​
Command Not Found: nvm

If you encounter the error zsh: command not found: nvm when attempting to install node, you might need to create the default profile file. The default shell is zsh on macOS, so create the profile file by running:
The default profile is bash for Ubuntu, including WSL, so use:
It’s fine to run if the file already exists. Then repeat the installation steps.

​
Version Compatibility Issues

The latest node version should work for most development projects, but be aware that some packages and tools have specific requirements. If you encounter issues, you might need to install and use a previous node version. Always check if the project has an .nvmrc file and use the node version indicated.

​
Required Node.js Versions

  • @wordpress/create-block: Requires node version 20.10.0 or above, and npm version 10.2.3 or above
  • @wordpress/scripts: Requires Node.js version with Active LTS or Maintenance LTS status

​
Additional Resources