This is a part of series of tutorials called: Building blocks of the building blocks.
This is a wonderful npm package, inspired by the official “quick start” package for the Mother of Gutenberg – React. Personally, I’m very excited to see this package growing into a real modern developer tool. Hell, I’m happy to see package.json among official WordPress files and, even though it’s not visible, to know that Webpack is there as well.
Now, let’s create that block.
Documentation doesn’t say from where I should run the command so I did it from WordPress root. Don’t do that. You should navigate to your wp-content/plugins folder and then run the command. The block files will be created in the current working folder, which was in my case WordPress root.
cd wp-content/plugins/
npm init @wordpress/block wordpress-blockI like the feedback you’re getting while the block is being created. After you get to the success line:
Done: block "WordPress Block" bootstrapped in the "wordpress-block" folder.you’ll get info on available commands:
# Starts the build for development.
npm start
# Builds the code for production.
npm run build
# Formats JavaScript files.
npm run format:js
# Lints CSS files.
npm run lint:css
# Lints JavaScript files.
npm run lint:js
# Updates WordPress packages to the latest version.
npm run packages-updateYou can start by navigating to your newly created plugin and running the script:
cd wordpress-block
npm startFile structure
The file structure is slightly different from the one from WP-CLI block.
wordpress-block/
├── build/
│ ├── index.js
│ └── index.asset.php
├── node_modules/
│ └── // let’s not go there now..
├── src/
│ ├── edit.js
│ ├── index.js
│ └── save.js
├── .editorconfig
├── .gitignore
├── editor.css
├── package.json
├── package-lock.json
├── readme.txt
├── style.css
└── wordpress-block.phpI’m not going to go into details about what each file is doing here, there will be a whole chapter dedicated to Block Anatomy. But I’d like to do a comparison with WP-CLI generated files. By the way, WP-CLI is used for building this tool.
WP-CLI @wprdpress/create-block
wpcli-block/ wp-content/
└── blocks/ plugins/
├── wpcli-plugin-block/ wordpress-block/
│ │ ├── build/
│ ├── index.js - - - - - - - -│ ├── index.js
│ │ │ └── index.asset.php
│ │ ├── node_modules/
│ │ ├── src/
│ │ │ ├── edit.js
│ │ │ ├── index.js
│ │ │ └── save.js
│ │ ├── .editorconfig
│ │ ├── .gitignore
│ ├── editor.css - - - - - - -├── editor.css
│ │ ├── package.json
│ │ ├── package-lock.json
│ │ ├── readme.txt
│ └── style.css - - - - - - - ├── style.css
└── wpcli-plugin-block.php - - -└── wordpress-block.phpSo, what is {plugin_name}/blocks/ folder in WP-CLI setup, here is the /wp-content/plugins/ folder. Folder inside /blocks/ folder is the root of the plugin. This means that, unlike with WP-CLI, with @wordpress/create-block package you can create only one block per plugin. Also, you can create blocks only as plugins and this is in accordance with currently allowed theme functionality for themes hosted at WordPress.org.
Moving on, in WP-CLI setup, {blockname}/index.js is the same file as {blockname}/build/index.js in @wordpress/create-block setup. However, the latter one is not the file where we write the code for the block. We write the code in Javascript files located in {blockname}/src/ folder. Running commands for building the block, located in the package.json file, all that code from /src/ folder will be compiled into a single file, index.js, and sent to /build/ folder.
Looking just at generated files, it appears that @wprdpress/create-block too doesn’t support SCSS file for styling. This is not true. This package is using @wordpress/scripts package as a dependency. You can see that in the package.json file. And @wordpress/scripts is a very powerful package, doing all the hard work with compiling, linting, testing and many other things. Looking at its documentation under default webpack config we can see css-loader, postcss-loader and sass-loader being included as well. These loaders are responsible for processing SCSS into CSS. We’ll go into greater detail on how to set this up later. For now it is important to know that this is possible and you don’t need additional dependencies to make this work.
In order to see this block in your editor, all you have to do is to activate the plugin. The block can be found in widgets category.
Usability
This package is using ESNext by default with the option to build a block with ES5. This is really nice. I prefer ESNext but if anyone wants to use vanilla Javascript they can just do it just as easily.
If you want to include SCSS in your block and use preprocessors for it, you need to do additional setup. It can be only creating a file but still this is not ready-to-use. I hope it will be improved in near future. And why is this not documented in @wordpress/create-block package documentation? Well, it was introduced in @wordpress/scripts v9.1.0 which was around 1,5 month ago at the time of this writing. It will be included in the official tutorial on creating blocks with @wordpress/create-block package, made by Marcus Kazmierczak.
There is one important thing to note here. Using style.scss (file name “style” is a problem) will stop the building process without any visible errors in the console. It appears that the issue is well known with possible solutions in Webpack 5. We’ll get into possible workarounds later.
Unlike WP-CLI, this package doesn’t modify the text domain, author, description etc of the plugin so you have to do it manually.
Remember when I said that Webpack is in there just not visible? That’s where it gets really interesting. That is the true nature of building with WordPress – extendibility. But that’s a whole another story. For now, I really like this tool for building blocks and looking forward to see its upcoming versions.
Useful links: