Getting Started

Gutenberg is built using the latest active LTS release of Node.js, along with the latest version of NPM.

The easiest way to install and manage node and NPM (on macOS, Linux, or Windows 10 with the Linux Subsystem) is by using nvm. Once nvm is installed, you can install the correct version of Node by running nvm install –latest-npm in the Gutenberg directory.

Note: If you find yourself needing to build older versions of Gutenberg, nvm makes that process easier too. Because Gutenberg’s .nvmrc file is regularly updated to the current available LTS release, running nvm install on an older branch will install whichever LTS version was active at that time.

Once you have Node installed, run these scripts from within your local Gutenberg repository:

Note: The install scripts require Python to be installed and in the path of the local system.

npm install
npm run build

This will build Gutenberg, ready to be used as a WordPress plugin!

npm run build is intended for one-off compilations of the project. If you’re planning to do continued development in the source files, using npm run dev will most often be the better option. This will configure the build to avoid minifying the generated output, rebuild files automatically as they are changed in your working directory, and configure dependencies as running in a development environment so that useful warnings and errors are logged to your browser’s developer console.

If you don’t have a local WordPress environment to load Gutenberg in, we can help get that up and running, too.

Local Environment

Step 1: Installing a Local Environment

The quickest way to get up and running is to use the wp-env command, which is developed within the Gutenberg source repository, and published as @wordpress/envto npm. In its default mode, it’ll install and run a local WordPress environment for you; however, it’s also possible to configure it to use a pre-existing local WordPress installation.

If you don’t already have it, you’ll need to install Docker and Docker Compose in order to use wp-env.

To install Docker, follow their instructions here for Windows 10 Proall other version of WindowsmacOS, or Linux. If running Ubuntu, see these extended instructions for help and troubleshooting.

To install Docker Compose, follow their instructions here, be sure to select your operating system for proper instructions.

Once Docker is installed and running, run this script to install WordPress, and build your local environment:

npx wp-env start

Step 2: Accessing and Configuring the Local WordPress Install

Accessing the Local WordPress Install

The WordPress installation should now be available at http://localhost:8888 (UsernameadminPasswordpassword). If this port is in use, you can override it using the WP_ENV_PORT environment variable. For more information, consult the wp-env README.

To shut down this local WordPress instance run npx wp-env stop. To start it back up again, run npx wp-env start again.

Toggling Debug Systems

WordPress comes with specific debug systems designed to simplify the process as well as standardize code across core, plugins and themes. In order to use with wp-env, you’ll have to edit your local WordPress install’s wp-config.php.


See the relevant section in wp-env docs.

On A Remote Server

You can use a remote server in development by building locally and then uploading the built files as a plugin to the remote server.

To build: open a terminal (or if on Windows, a command prompt) and navigate to the repository you cloned. Now type npm install to get the dependencies all set up. Once that finishes, you can type npm run build.

After building the cloned gutenberg directory contains the complete plugin, you can upload the entire repository to your wp-content/plugins directory and activate the plugin from the WordPress admin.

Another way to upload after building is to run npm run build:plugin-zip to create a plugin zip file — this requires bash and php to run. The script creates gutenberg.zipthat you can use to install Gutenberg through the WordPress admin.


Storybook is an open source tool for developing UI components in isolation for React, React Native and more. It makes building stunning UIs organized and efficient.

The Gutenberg repository also includes Storybook integration that allows testing and developing in a WordPress-agnostic context. This is very helpful for developing reusable components and trying generic JavaScript modules without any backend dependency.

You can launch Storybook by running npm run storybook:dev locally. It will open in your browser automatically.

You can also test Storybook for the current master branch on GitHub Pages:

Developer Tools

We recommend configuring your editor to automatically check for syntax and lint errors. This will help you save time as you develop by automatically fixing minor formatting issues. Here are some directions for setting up Visual Studio Code, a popular editor used by many of the core developers, these tools are also available for other editors.


EditorConfig defines a standard configuration for setting up your editor, for example using tabs instead of spaces. You should install the EditorConfig for VS Codeextension and it will automatically configure your editor to match the rules defined in .editorconfig.


ESLint statically analyzes the code to find problems. The lint rules are integrated in the continuous integration process and must pass to be able to commit. You should install the ESLint Extension for Visual Studio Code, see eslint docs for more editor integrations.

With the extension installed, ESLint will use the .eslintrc.js file in the root of the Gutenberg repository for formatting rules. It will highlight issues as you develop, you can also set the following preference to fix lint rules on save.

    "editor.codeActionsOnSave": {
        "source.fixAll.eslint": true


Prettier is a tool that allows you to define an opinionated format, and automate fixing the code to match that format. Prettier and ESlint are similar, Prettier is more about formatting and style, while ESlint is for detecting coding errors.

To use Prettier with Visual Studio Code, you should install the Prettier – Code formatter extension. You can then configure it to be the default formatter and to automatically fix issues on save, by adding the following to your settings.

"\[javascript\]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
"\[markdown\]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true

This will use the .prettierrc.js file included in the root of the Gutenberg repository. The config is included from the @wordpress/prettier-config package.

If you only want to use this configuration with the Gutenberg project, create a directory called .vscode at the top-level of Gutenberg, and place your settings in a settings.json there. Visual Studio Code refers to this as Workplace Settings, and only apply to the project.

For other editors, see Prettier’s Editor Integration docs


TypeScript is a typed superset of JavaScript language. The Gutenberg project uses TypeScript via JSDoc to type check JavaScript files. If you use Visual Studio Code, TypeScript support is built-in, otherwise see TypeScript Editor Support for editor integrations.