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: 
npx @wordpress/create-block@latest my-block

​
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.
1
Install nvm
2
Open the terminal and run the following to install nvm. On macOS, the required developer tools are not installed by default. Install them if prompted.
3
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
4
Restart Terminal
5
Quit and restart the terminal to ensure nvm is loaded.
6
Install Node.js LTS
7
Run the following command to install the latest LTS (Long Term Support) version of Node.js:
8
nvm install --lts
9
Verify Installation
10
Run the following commands to verify the installed node and npm versions:
11
node -v
npm -v

​
Managing Node Versions with nvm

If needed, you can install specific versions of node. For example, install version 18 by running: 
nvm install 18
Switch between different versions by running: 
nvm use [version-number]
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: 
nvm install [version-number]
nvm use

​
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.
1
Download Node.js Installer
2
Visit the Node.js download page and download the Windows installer.
3
Run the Installer
4
Double-click the downloaded file and follow the installation wizard. Accept the default settings unless you have specific requirements.
5
Verify Installation
6
Open Command Prompt or PowerShell and run:
7
node -v
npm -v
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: 
npm install
npm run build
npm run start

​
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: 
touch ~/.zshrc
The default profile is bash for Ubuntu, including WSL, so use: 
touch ~/.bashrc
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

Build docs developers (and LLMs) love

Get started for freeTalk to us