Plugin Gutenberg Blocks

This is a boilerplate for adding multiple blocks within a plugin. If you wish to add blocks to your theme rather than via a plugin please use Theme Gutenberg Blocks.

Table of Contents

1. Directory Structure
2. Getting started
3. Customisation
   1. Webpack
   2. New Blocks
   3. Multiple vs Combined Block Asset Files
4. Build
5. TODO

Directory Structure

The following is the basic directory structure.

├── /blocks - All the custom blocks that will be automatically registered.
├── /build - Default directory that the block bundles get added to from the wp-script commands within the package.json.
├── /node_modules - Bundles.
├── /src - Contains the index.js file that is the source for the bundling commands, this automatically imports all the custom blocks from the /blocks directory, assuming they contain a index.js file.
├── /blocks-bootstrap.php - The PHP code that runs the WP functions to automatically register blocks from the /blocks directory. This uses glob patterns to autoload blocks, see New Blocks
├── /package.json - The package json.
├── /package-lock.json - The package json lock file.
├── /README.md - This file.
└── /webpack.config.js - The webpack configuration that extends on the node_modules/@wordpress/scripts/config/webpack.config.js Config.

Getting Started

This section details the beginning of the setup within your plugin.

1. Place a copy of this directory within your plugins.
2. Rename the files and strings for the plugins name etc.
3. Navigate to the plugin directory and run the commands for the build. This is assuming its still called plugin-gutenberg-blocks

cd wp-content/plugins/plugin-gutenberg-blocks
npm install
npm run build

Customisation

There are several customisations that can be done.

Webpack

The webpack.config.js file in this directory extends the default located here node_modules/@wordpress/scripts/config/webpack.config.js. Any additional webpack customisations that extend or overwrites the WordPress scripts default should go in this file.

New Blocks

within blocks directory lays all the custom blocks that will be bundled. The directory has, first-block, second-block and third-block. They can be renamed or removed, they are simply there to provide an example.

Every custom block will reside within their own directory within blocks directory. The format is as per WordPress current information(WP 5.9.3) see How-to Guides / Blocks. In this instance each block does not need any package bundler files as this is handled in the plugin root directory.

Required

Each block requires a directory of its own, named after its block, i.e. first-block. Within this directory the following files can be used;
└── /blocks
  └── /block-name
    ├── /args.php - Optional. Not a WordPress default. This is used within the bootstrap file when auto registering all the blocks. This is optional and can be removed. See register_block_type() @param $args.
    ├── /block.json - The settings and other metadata should be defined in a block.json file.
    ├── /edit.js - The edit functionality, which is a component that is shown in the editor when the block gets inserted.
    ├── /editor.scss - Contains any CSS code that gets applied to the editor.
    ├── /index.js - Registers a new block, combining asset files within said block directory.
    ├── /save.js - The save function defines the way in which the different attributes should be combined into the final markup, which is then serialized by the block editor into post_content.
    └── /style.scss - Applied both on the front of your site and in the editor.

Register the new block

That's it, the block will be auto registered based on the above files, and the block will be auto bundled next time the script is run from the root directory of this plugin.

Multiple vs Combined Block Asset Files

Currently, the webpack file has a variable to change the way that the build is done. This variable is defined as multipleEntryPoint, which is a boolean and if its true the webpack builder will create asset files for each block and not combine them. One caveat with this is that the block.json file for each block needs to point at the correct asset files that are built.

The examples in this directory are using the multiple entry points, so each block has individual asset files, this can be seen within these lines;

{
  "editorScript": "file:../../build/first-block.js",
  "editorStyle": "file:../../build/first-block.css",
  "style": "file:../../build/style-first-block.css"
}

The opposite would be that multipleEntryPoint is set to false within the webpack.config.js file, then the block.json would have lines like this;

{
  "editorScript": "file:../../build/index.js",
  "editorStyle": "file:../../build/index.css",
  "style": "file:../../build/style-index.css"
}

Build

If your site runs a build on deploy, and you want this plugin included, you can gitignore the ./build dir and add the script to your pipelines or similar build process. I do not advise this for plugins, and prefer to commit build files, I only prefer the build process for themes and MU Plugins. If the plugin is not included in a site build, remember to run the build before every commit to the repository.

TODO

The following would be nice to address at some point, and advice would be welcome.

• Find a way for the variable used within the webpack file could be globally set multipleEntryPoint, so that it's passed to the webpack.config.js for the entry points. In addition it would be used to automatically update the block.json files for each of the custom blocks, dictating the "editorScript", "editorStyle", and "style" keys.