How to Use @wordpress/scripts when Creating a Gutenberg Block

Let’s begin with the understanding that you can not use regular JavaScript when creating blocks for Gutenberg. Well, you could try, of course, but the code will be hardly readable. Believe me, I know what I’m talking about because when I started learning blocks in 2019 with regular JavaScript, I didn’t use JSX.

My React code in vanilla JavaScript could look something like this:

return (
	wp.element.createElement( wp.element.Fragment, {},
		wp.element.createElement( wp.editor.InspectorControls, {},
			wp.element.createElement( wp.editor.PanelColorSettings,
				{
					title: 'Awesome Color Options',
					colorSettings: [
						{
							colors: colorSamples,
							value: props.formColor.color,
							label: 'Form Color',
							onChange: props.setFormColor,
						}
					]
				},
			),
		),
		wp.element.createElement( 'div', { className: formClasses },
			wp.element.createElement( 'div', { className: 'misha-form-wrap' },
				wp.element.createElement( 'div', {},
					'Enter your email...'
				),
				wp.element.createElement( 'div', { style: buttonStyles },
					'Subscribe'
				)
			)
		)
	)
);

Considering that in this tutorial, I tried to simplify it by assigning some constants like const el = wp.element.createElement() or const Fragment = wp.element.Fragment.

All right, now, check how the same piece of code looks when written with JSX:

return (
	<Fragment>
		<InspectorControls>
			<PanelColorSettings
				title="Awesome Color Options"
				colorSettings={[
					{
						colors: colorSamples,
						value: props.formColor.color,
						label: 'Form Color',
						onChange: props.setFormColor,
					}
				]}
			/>
		</InspectorControls>
		<div className={ formClasses }>
			<div className="misha-form-wrap">
				<div>Enter your email...</div>
				<div style={ buttonStyles }>Subscribe</div>
			</div>
		</div>
	</Fragment>
)

The code looks like a kind of HTML code, where each React component is presented as an HTML tag, let’s say, for example <PanelColorSettings>.

Perhaps, in small code snippets, you don’t feel the difference, but not if you’re developing a really complicated Gutenberg block.

So, as you can see here, writing JavaScript code in JSX is like writing HTML. This approach, by the way, is used not only by WordPress Gutenberg block developers but also by any React developers.

It allows us to transform the following code:

wp.element.createElement( MyElement, props, children...  )

Into this:

<MyElement prop={}>children</MyElement>

So, every React (or Gutenberg) component now looks like an HTML tag. And when you need some HTML tags inside your block, then you just write HTML almost without changes.

One more thing I want to highlight for you here is that sometimes (well, actually, every time), when creating a block, you may need some additional Gutenberg components for it. It could be InspectorControls (when you create panels with block settings) or PanelColorSettings (when you add color palettes to a block) or even the registerBlockType() function that is required for any block anyway.

Just start your JavaScript file with some import tags to make the components you need available inside the file.

import { Fragment } from "@wordpress/element";

import {
	InspectorControls,
	PanelColorSettings
} from '@wordpress/block-editor';

Think of it like an analogy to the include() function in PHP.

How to Start Using JSX?

Ok, I hope I convinced you that JSX is great for block development. But there is a small problem – browsers simply don’t understand JSX. That’s why we need to use Webpack or, in our case, the @wordpress/scripts library (it works with Webpack anyway) to automatically compile your JSX code into browser-readable code.

The whole idea here is to have two folders for your JavaScript files:

• /src – a folder with source files that are written with JSX,
• /build – a folder with compiled files, which are ready to use in browsers.

And what Webpack does here is automatically generate the files in the build folders.

Configuring Webpack for the first time is not the easiest thing to do, but we don’t need it, because @wordpress/scripts does everything for us.

Honestly, the struggles with this step are usually so unbearable for WordPress developers that they are ready to throw the performance of their project under the train and create blocks with PHP and some plugins, like, for example, Advanced Custom Fields (ACF).

So, my goal in this video course is to show you that everything is not as difficult as it may seem; you just need to figure out some basics.

Installing @wordpress/scripts

The good news here is that we only need one NPM module to install.

npm install @wordpress/scripts --save-dev

But before that, check that your Node.js version is higher than 14.0 by running a command node --version and also that the NPM version is 6.14.4 or above with npm --version.

Already getting lost?

If you have no idea where to run this code or even what Node.js is and how to use it, never worry, just watch the video above where I do everything completely from scratch

Difference between “wp-scripts start” and “wp-scripts build”

Once installation is done, we have a bunch of scripts to use, and you can find all of them in the official WordPress documentation, but when we develop blocks for Gutenberg, we only need a handful of them.

Here they are:

• wp-scripts start – when we run this command, Webpack starts to watch for changes made in the src/index.js file (more about file structure below), and every time you “Save” or use Cmd + S, it compiles the browser-ready code of the block. To exit the watching mode, press Ctrl + C (on Mac OS).
• wp-scripts build – it compiles the block code for production mode and minifies the result JavaScript. Run it when you finish the development work.

But one more thing, to have the possibility to run these scripts in the command line, we need to add them to the package.json file, which is a part of your project now.

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

Once done, we can run the scripts using the NPM command npm run <script name>.

Understanding the file structure

A little bit above, I showed you an example of file structure:

• src/index.js – is a fallback entry point used by @wordpress/scripts
• build/index.js – is the default output file.

So you can just create these two files, and it is going to be pretty much it.

But it also supports some custom script names, but in this case, you have to locate your block.json file in the src folder and then set one of the parameters – editorScript, script or viewScript. Example:

{
	"editorScript" : "file:editor.js"
}

And this is the new file structure:

This approach could be helpful when you have multiple blocks within a single WordPress plugin (or theme), but it is not the only way. We are going to talk about it in a separate lesson.

Gutenberg Block Development

Misha Rudrastyh

Hey guys and welcome to my website. For more than 10 years I've been doing my best to share with you some superb WordPress guides and tips for free.

Need some developer help? Contact me

Follow me on X