We don’t want to spend our precious free-time configuring Webpack and managing dependencies! We want to get started developing awesome blocks now! Thankfully tools like Create Guten Block make it easy to start.
Enter Create Guten Block
Once installed, running Create Guten Block’s
npx create-guten-block my-block in your plugins directory will get you setup with a plugin following Gutenberg block development best practices. Including support for ES6+, JSX, CSS prefixing, and a snazzy build process.
Running Create Guten Block for the First Time
Note: If you run into issues with your version of Node and CGB check out nvm for managing your node version.
You’ll want to have a local WordPress environment setup and installed before we begin.
Now within Terminal you’ll navigate to the
wp-content/plugins directory of your WordPress install and run
npx create-guten-block my-block. Replacing
my-block with your new plugin name.
Then when you’re ready to start editing our blocks you navigate to your plugin directory and run
But first let’s take a look at what exactly that gives us.
Note: If you need some help getting your first block started with CGB check out this post from Atomic Blocks.
Create Guten Block Plugin Structure
Once you’ve fired up a piping hot block-ready plugin using Create Guten Block you’ll need to know a little about the plugin structure.
plugins/my-block // Hidden linting files ├── .editorconfig ├── .eslintignore ├── .eslinrtc // Distribution folder containing compiled block JS and CSS ├── dist/ ├── blocks.build.js ├── blocks.editor.build.css ├── blocks.style.build.css // All the node modules CGB handles for you ├── node_modules/ // Configuration files. AKA if you don't know it, don't touch it. ├── packages-lock.json ├── package.json // File initializing and defining your plugin. Rename to 'your-plugin-name.php' ├── plugin.php // Information about the plugin. You'll want a readme.txt for submitting to WordPress.org (https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/) ├── README.md // The source files you'll be editing ├── src/ // The directory containing your individual block JS and SCSS ├── block/ ├── block.js ├── editor.scss ├── stylce.scss // The file webpack compiles defining your block(s) ├── blocks.js // SCSS for including variable and mixins to be used throughout blocks ├── commons.scss // Where your block scripts and styles are enqueued ├── init.php
Some of these you’re not going to want to concern yourself with unless you know what you’re doing. I’m looking at you node_modules, package-lock.json, pacakage.json, and hidden dot files. But let’s take deeper look at some of the more important files
This file is used to define your plugin. You’ll likely want to rename this file to match your plugin’s name to stick to WordPress plugin best practices.
You’ll definitely want to go through and update the header information to list yourself as the author and update your plugin name and description.
The src/ directory is the good stuff. This is where all of the files we’ll actually be editing are stored.
First up is the block/ directory. This contains three files right off the bat. Our block.js, editor.scss, and style.scss. These files make the foundation of our block.
block.js is going to be where we do most of the building of our block.
Within your block.js file you’ll want to update your block namespace from
cgb/block-name to something using the
plugin-name/block-name format to keep with best practices.
editor.scss is the styles used only in the editor while style.scss will contain styles used by both the editor and front-end output of our block.
You’ll notice in your block.js file that the editor.scss and style.scss files are be imported. Webpack uses these imports to build out our final CSS files to be enqueued for the block.
For a more detailed breakdown of what to enqueue on the editor vs frontend check out my post on enqueueing scripts and styles for blocks.
Now hopping back to the root of the src/ directory we’ve got the common.scss file that can be used to store variables that are to be used across the project.
We also have init.php which is being used to enqueue the scripts and styles that our compiled into the dist/ folder.
Then finally we have blocks.js which is used by webpack to compile the block or blocks of our plugin.
Adding Multiple Blocks
There’s a good chance you may want to build more than one block in your plugin. And with Create Guten Block it couldn’t be easier.
The first thing you’ll want to do is
Crack open the blocks.js file and you’ll see the following line
This line tells webpack to grab the block.js folder from the block/ directory in our plugin. If you’d like to rename your block to something a little more catchy you could rename the folder then update it here.
If you want to create a second block all you need to do is duplicate the existing block/ directory, rename it, and add a new import inside blocks.js.
So if we want to create a new dynamic block we could name our folder dynamic-block/ and then to register both blocks are blocks.js file would have:
import './block/block.js' import './dynamic-block/block.js'
If you’ve got
npm start running CGB will compile the new block and you’ll be up and running and ready to edit away.
Where To Put Dynamic Blocks Callbacks
Speaking of dynamic blocks if you’ve read my past article you know that dynamic blocks require the use of a PHP callback function to render data from the server. So where does that PHP function go?
I’d suggest dropping it in the init.php file for a simple plugin. You do register blocks in PHP on the
init action after all.
But you’re welcome to add directories to your plugin and organize to your hearts content. WordPress is open source of course, so you do you. But hopefully this guide gives you a basic understanding to what Create Guten Block gets you started with out of the gate.
It’s a must-have for developers looking to build their first blocks in the new WordPress editor. 👍