Gutenberg Tutorials: #2 How to Manage Dependencies when you do wp_register_script

Check out my first tutorial in my Gutenberg Tutorials series: Gutenberg Tutorials: #1 How to Build a Simple Gutenberg Block with Webpack and the next tutorial Gutenberg Tutorials: #3 Attributes — Demonstrated and Explained.

Welcome to the second tutorial in my Gutenberg Tutorials series! Last time, we got our simple Gutenberg block built by a basic Webpack setup up and running. This time, we’re going to focus on how to get the correct and required dependencies set when we register our editor script with wp_register_script. This is a pretty important step and we should get this right as soon as possible. It is a pain in the ass to manually check what Gutenberg packages you have imported and then add the corresponding script handles in the $deps argument in wp_register_script. Worse still, you aren’t 100% sure how to map Gutenberg packages to their corresponding script handles.

Solution: the Dependency Extraction Webpack Plugin

It took me a while to find the relevant information on how to manage the dependencies for Gutenberg Block development in the official guides. Turns out the key information is mentioned here, and let me quote:

If you’re building a plugin that runs on WordPress, you’d probably prefer consuming the package that ships with WordPress itself. This allows multiple plugins to reuse the same packages and avoid code duplication. In WordPress, these packages are available as WordPress scripts with a handle following this format wp-package-name (e.g. wp-components). Once you add the script to your own WordPress plugin scripts dependencies, the package will be available on the wp global variable.

Script dependencies definition can be a tedious task for developers. Mistakes and oversight can happen easily. If you want to learn how you can automate this task. Check the @wordpress/scripts and @wordpress/dependency-extraction-webpack-plugin documentation.

So even if you want to do this manually, you can follow its wp-package-name format to get the correct script handles of the dependencies from this list of packages.

But we are lazy developers, right? We rejoice on every chance we can automate and simplify things! Actually, it is really simple to make use of the Dependency Extraction Webpack Plugin.

Firstly, add it in the plugins list in your webpack.config.js:

// webpack.config.js
const DependencyExtractionWebpackPlugin = require( '@wordpress/dependency-extraction-webpack-plugin' );

module.exports = {
	// …snip
	plugins: [ new DependencyExtractionWebpackPlugin() ],
};

Then, make sure you import the Gutenberg packages in your entrypoint/editor script from the ‘@wordpress/*’ packages, e.g. like this:

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps } from '@wordpress/block-editor';

Next, build your Webpack bundles. Your should find a [script_name].asset.php file being generated in your build folder with contents like this:

<?php return array('dependencies' => array('wp-block-editor', 'wp-blocks', 'wp-element'), 'version' => '6879812dfc518f8a3942e4a540142e0e');

Finally, use the dependencies and version values in your call to wp_register_script from the generated [script_name].asset.php file:

$editor_asset = include( plugin_dir_path( __FILE__ ) . 'build/editor.asset.php');
wp_register_script(
    'gtg-demo-editor-script',
    plugins_url( 'build/editor.js', __FILE__ ),
    $editor_asset['dependencies'],
    $editor_asset['version']
);

For your editor css file, you should add the ‘wp-edit-blocks’ dependency demonstrated in the official tutorial, like this:

wp_register_style(
    'gtg-demo-editor-style',
    plugins_url( 'build/editor.css', __FILE__ ),
    ['wp-edit-blocks'],
    filemtime( plugin_dir_path( __FILE__ ) . 'build/editor.css' )
);

And Voila! By following these steps, you will never have to worry about setting the wrong dependencies for your Gutenberg Block script ever again!