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
.nvmrcfile is regularly updated to the current available LTS release, runningnvm installon 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 buildThis 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.
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/env to 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 Pro, all other version of Windows, macOS, 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 startThe WordPress installation should now be available at http:https://localhost:8888 (Username: admin, Password: password).
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.
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.
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.zip that 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: https://wordpress.github.io/gutenberg/
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 Code extension 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.