To get started building blocks for Gutenberg we’re going to need a way to let WordPress know our blocks exist.
Since Gutenberg blocks are built with JavaScript we’ll need to enqueue our scripts and any styles associated with the block.
This is done by using two new hooks introduced to WordPress specifically for enqueueing block assets. As well as the wp_enqueue_script and wp_enqueue_style functions.
The new hooks
enqueue_block_editor_assets – This can be used to enqueue block scripts and styles in the admin editor only.
enqueue_block_assets – This is used to enqueue block scripts and styles in both the admin editor and frontend of the site.
What to enqueue in the admin only
Since the main JavaScript for creating blocks is only needed in the admin editor you’ll want to use enqueue_block_editor_assets to include it.
You may also have styles that are only relevant to the editor. In that case you’ll want to enqueue those using enqueue_block_editor_assets as well. This could be something like focus states for an input or other indicators to show the user what is editable in the editor that isn’t needed on the frontend.
What to enqueue in the frontend only
In some cases you may need JavaScript that runs in both the frontend or the backend. For example, if you’re building a slider block you would want the sliding functionality to work in both instances. In that case you can load those scripts with enqueue_block_assets.
Since the idea behind Gutenberg is to tie the frontend and editor content together visually you’ll most likely have the bulk of your CSS displayed on both the frontend and editor. This again would use enqueue_block_assets.
In the case you have some style that needs to only be included within the frontend and not the editor you could use the enqueue_block_assets hook and run an ! is_admin() check to enqueue your script or style.
A word on dependencies
When you’re building blocks for the new Gutenberg editor there are a few JavaScript libraries that you’ll want to include within the dependencies parameter of your wp_enqueue_script function.
These are wp-element, wp-blocks, wp-components, wp-i18n, and wp-editor for JS. And wp-edit-blocks for styles in the editor. These will give you access to several powerful tools to make your life developing blocks easier.
At a minimum, you will need to enqueue scripts for your block as part of a enqueue_block_editor_assets action callback, with a dependency on the
wp-blocksandwp-elementscript handles.
Let’s take a look at what these cover.
wp-element – This handle gives access to wp.element which is an abstraction layer atop of Reach that can be used for creating elements. Having an abstraction layer allows WordPress to safeguard against any future changes to React by have a centralized version of the code. Check out the Github readme on Element for more information.
wp-blocks – This handle refers to wp.blocks which gives access to components and functions used for building blocks. Things like registerBlockType are found here. Again you can find more details on the Github readme on Blocks.
wp-components – While not required like wp-element and wp-blocks, the wp-components library is helpful in block development as it contains React components that can be used to create a consistent editor experience. Things like tooltips, popovers, and spinners can be found here. Explore the Github directory for Components to see what else is available.
wp-i18n – Again this isn’t required, but it is a good practice to include as this gives you easy access to the internationalization functions that can be used within JavaScript. If you’re familiar with the __() used within WordPress you’ll be able to use this in a similar fashion within JavaScript.
wp-editor -This handles the BlockControls and RichText components. For more see the Github directory for Editor.
wp-edit-blocks – This is a handle for CSS that is already dependent on wp-components, wp-editor, wp-block-library, and wp-block-library-theme. So using it as your dependency for styles for the editor will make sure the styles related to those handles are enqueued as well.
Let’s pretend we’re using this in a plugin hence the plugins_url() path.
Putting it together
Now that we know what we’re working with we can confidently start enqueueing scripts and styles for Gutenberg blocks. Let’s put it all together.
<?php
/**
* Enqueue block JavaScript and CSS for the editor
*/
function my_block_plugin_editor_scripts() {
// Enqueue block editor JS
wp_enqueue_script(
'my-block-editor-js',
plugins_url( '/blocks/custom-block/index.js', __FILE__ ),
[ 'wp-blocks', 'wp-i18n', 'wp-element', 'wp-components', 'wp-editor' ],
filemtime( plugin_dir_path( __FILE__ ) . 'blocks/custom-block/index.js' )
);
// Enqueue block editor styles
wp_enqueue_style(
'my-block-editor-css',
plugins_url( '/blocks/custom-block/editor-styles.css', __FILE__ ),
[ 'wp-edit-blocks' ],
filemtime( plugin_dir_path( __FILE__ ) . 'blocks/custom-block/editor-styles.css' )
);
}
// Hook the enqueue functions into the editor
add_action( 'enqueue_block_editor_assets', 'my_block_plugin_editor_scripts' );
/**
* Enqueue frontend and editor JavaScript and CSS
*/
function my_block_plugin_scripts() {
// Enqueue block editor styles
wp_enqueue_style(
'my-block-css',
plugins_url( '/blocks/custom-block/styles.css', __FILE__ ),
[],
filemtime( plugin_dir_path( __FILE__ ) . 'blocks/custom-block/styles.css' )
);
}
// Hook the enqueue functions into the frontend and editor
add_action( 'enqueue_block_assets', 'my_block_plugin_scripts' );
Even though we’re showing an example of enqueueing block scripts and styles in a plugin here. You could also enqueue styles from within a theme to make sure blocks fit your design.
In fact there’s an interesting ticket on Github now discussing how base and theme block assets will be bundled and loaded with Gutenberg.
But wait there’s more!
So now that we’ve gone through enqueueing assets with enqueue_block_editor_assets and enqeueue_block_assets I should point out there is another way.
If you look at the handbook1, you’ll see it shows enqueueing scripts and styles a different way.
Instead of using the enqueue hooks we’ve gone over, the script and styles are registered with wp_register_script and wp_register_style. Then passed to the register_block_type function registration settings.
There are 4 options to use in this method:
editor_script and editor_style which are only enqueued in the editor. And script and style which are enqueued on both the editor and when viewing the frontend.
All done within the init hook. Here’s an example from the handbook.
<?php
function gutenberg_boilerplate_block() {
wp_register_script(
'gutenberg-boilerplate-es5-step01',
plugins_url( 'step-01/block.js', __FILE__ ),
array( 'wp-blocks', 'wp-element' )
);
register_block_type( 'gutenberg-boilerplate-es5/hello-world-step-01', array(
'editor_script' => 'gutenberg-boilerplate-es5-step01',
) );
}
add_action( 'init', 'gutenberg_boilerplate_block' );
I prefer the enqueue_block_editor_assets and enqueue_block_assets methods. It’s more inline with the current method for adding editor styles using add_editor_style. And you have flexibility for enqueueing multiple files. If that use case arises.
Resources on Enqueueing Scripts and Styles for Gutenberg Blocks
Big thanks to Zac Gordon for his The Gutenberg Development Course for getting my research into this topic started. I highly recommend you take it.
