How to Set Up a Development Environment for Gutenberg

This instruction is for anyone who wants to write Gutenberg code in ES6, ESNext, or JSX, and then use webpack and babel to turn it into files that can be used in the Gutenberg editor. We’ll look at what you need to do, why you need to do it, and how we can expand and alter WordPress’ defaults to meet our needs.

If you’re unfamiliar with the ideas of npm, webpcak, and Babel, you should read the next section, which explains the fundamentals of how these tools function and how to utilize them. Skip forward to the next section where we’ll really set things up if you’ve done this previously and are comfortable with the process, possibly via programming with React.

For beginners: npm, webpack, and Babel

If this is your first time, you’ll need to download and install Node.js on your computer. Download and install it by clicking the link. You’ll find a tool in Node.js that we’ll utilize to set up the majority of the configuration. npm is a command-line / terminal tool that allows you to install Javascript libraries and run scripts. If you want, you can use yarn instead of npm, but for the purposes of this guide, we’ll use npm.

npm

This guide will not go through all of the things you can do with npm in-depth, but it will cover the basics and things that are important for our purposes. We’ll use npm for two things: installing necessary libraries and running commands to build (compile) our Javascript scripts.

You can install any open-source Javascript package with npm. We’d need to install React libraries and webpack libraries if we wanted to develop with React outside of WordPress. You can install a variety of libraries (mostly for Gutenberg) in WordPress, but we’re just interested in one: @wordpress/scripts, which simplifies our settings.

When you install a library, npm creates a subfolder called “node modules” in which the libraries are stored. You’ll never need to access or edit anything in this folder, but keep in mind that it might easily contain tens of thousands of files. You should never commit this folder to git or include it in a completed theme or plugin. The libraries are only required during the development phase.

You can use npm to run scripts defined in your package.json file once your environment is set up. Depending on the project, at least two scripts are required: one to construct the scripts and another to activate “watch mode.” In “watch mode,” npm spawns a process in the terminal that watches for and listens for changes to any file, compiling them at runtime whenever you hit save. If you’ve used the SCSS or LESS compiler programs before, you’re probably familiar with this notion. Instead of going to the terminal and running the build command after every update, it’s far more effective to run a “watch” script in the background that recompiles every time you save.

webpack and babel

You can get by with no webpack or babel settings when building for Gutenberg. We won’t have to worry about it because we’re using WordPress’ libraries. However, there is one disadvantage: both your source and output files will be saved in the same directory and with the same name. Your entire Javascript development should be contained in a single file, project-folder/src/index.js, and the build should always be contained in project-folder/build/index.js. If you’re okay with it, you may go forward to the webpack configuration section. If you’re making a theme or plugin with a lot of Gutenberg features (custom blocks, filters, etc. ), you’ll probably want a distinct output filename and location, as well as the ability to have several files.

Babel is already installed if you use the WordPress scripts package (@wordpress/scripts). However, you should be aware that the WordPress bundle may not include all of the plugins you require. For example, there is a package that allows you to define functions without having to bind them using the new “arrow functions” ( myFunction = (param) => { } ). If you insist on using certain ESNext features, you’ll have to set up Babel yourself rather than relying on WordPress’ defaults.

The process

Once everything is set up and installed, you can start developing with webpack by going to your project folder in the terminal and running the “watch” script. It’ll stay open and keep track of any modifications you make to your JS files. The terminal will output information (hopefully) indicating it has successfully re-compiled the file whenever you hit save in your Javascript files. There will be a message in the terminal if there were any compilation errors. CTRL + C will halt the “watch” process.

Setting up the environment

I’m assuming you already have a local WordPress installation running on a LAMP stack (programs like WampServer, XAMPP, Docker, or something similar), and that you’ve got a plugin or theme ready to start writing Javascript in.

Because you may wind up with multiple config files and folders, I propose creating a subfolder dedicated to your Javascript work. This makes it easy to isolate files and folders that you don’t want to include in git commits or final builds (for example, node modules/). However, using your main theme or plugin folder as a project folder for Javascript development is entirely acceptable.

Navigate to your project folder in terminal (Mac OS terminal or Windows Command Prompt both work great). For the purposes of this article, I’ll assume we’re in a theme and have created a gutenberg-dev/ subdirectory as our project folder.

The first step is to create an npm project, which entails telling npm to create a package.json file. This package.json file tells npm which packages are necessary and which scripts are ready to run. Put this in the terminal: npm init -y

We’ll then install the WordPress package, which will assist us to reduce the amount of configuration we’ll have to complete. Run the following command: npm install –save-dev –save-exact @wordpress/scripts.

The tag —save-dev tells npm that the provided libraries are only required for development, and —save-exact ensures that npm only installs the most recent version.

In your editor, open the package.json file. (A package-lock.json file will be generated by npm when you install packages; disregard this file; you’ll be making modifications to package.json). It should be populated with default configuration, and you may observe that the package installation we did earlier created an entry in devDependencies for @wordpress/scripts of a specific version. As you install more packages, npm will add entries for each package to package.json. The scripts property, which is for scripts (commands) that you may run using npm, is all we need to worry about in this file. Replace the default “test” in the scripts property with the following:

"scripts": {
	"build": "wp-scripts build",
	"start": "wp-scripts start"
},

This line of code notifies npm that there are two scripts in this project folder that we can run: “build” and “start.” We run a script using the command npm run script-name, in which npm searches package.json for the command specified as its value and executes it.

We can also use WordPress’ webpack and Babel config instead of having to do it ourselves.

Make a subfolder called src/ in your project folder. Make an index.js file in this folder.

You’re done if you’re OK with the defaults in Webpack. In index.js, write your ES6 and JSX code, and instruct npm to compile it by using the build command:

npm run build

or, in the terminal, launch a “watch” process that listens for changes made using this command (use CTRL+C to quit the watching process):

npm run start

If you run either of these, a build/ subdirectory will be created in your project directory, with the compiled result in build/index.js.

That concludes the most fundamental environment setup! You’re now ready to start writing Gutenberg ES6 Javascript!