mkaz.blog

Make your own create-block templates

Did you know the create-block script can support templates? With templates you can create your own files to be generated for a new block. I see this being quite useful especially if you are an agency or business that creates many custom blocks, or for developers to share different block starting points.

What is the create-block script?

First off, if you aren't familiar the @wordpress/create-block package allows you to stub out a simple block with the complete set of scripts and tooling needed to build a block. You can see a full example of this in the official Create a Block Tutorial.

However, the default block created is relatively simple with no attributes, and just a static edit and save functions. The official tutorial will walk you through the steps needed to make it a dynamic block.

A template exists in the Gutenberg repo with the final state after the tutorial, see the create-block-tutorial-template package. You can invoke this template using:

npx @wordpress/create-block --template @wordpress/create-block-tutorial-template

If you don't pass a block name or parameters, you will be prompted to fill in the details.

You can pass those values on the command-line see npx @wordpress/create-block --help for the list of available parameters.

Here's an example with a block slug, title, namespace, description, and category:

npx @wordpress/create-block awesome-block-slug \
    --template @wordpress/create-block-tutorial-template \
    --title "Awesome Block" \
    --namespace mkaz \
    --short-description "Another awesome block" \
    --category "widgets"

Create your own template

You can create your own template package, so the blocks generated match a starting point of your choice. The create-block tool supports external template packages either as a local directory or hosted as an NPM package. The external package consists of an index.js file and a set of mustache templates that it will transform to the files for your block.

The minimum for your template is:

const { join } = require("path");
 
module.exports = {
    templatesPath: join(__dirname, "templates"),
};

You likely will want to set your own defaultValues:

const { join } = require("path");
 
module.exports = {
    defaultValues: {
        slug: "richtext-block",
        namespace: "mkaz",
        author: "Marcus Kazmierczak",
        title: "My RichText block",
        dashicon: "hammer",
        version: "0.1.0",
    },
    templatesPath: join(__dirname, "templates"),
};

In this example, my custom template package will include a directory called templates/ that will include .mustache files that get transformed. For example: readme.txt.mustache will be transformed using the defaultValues as variables and a readme.txt file will be created.

Here's the full directory tree for my template package:

 mkaz-block-template/
 ├── templates/
 │  ├── src/
 │  │  ├── edit.js.mustache
 │  │  ├── editor.scss.mustache
 │  │  ├── index.js.mustache
 │  │  ├── save.js.mustache
 │  │  └── style.scss.mustache
 │  ├── $slug.php.mustache
 │  └── readme.txt.mustache
 ├── index.js
 ├── package.json
 └── README.md

Mustache is a JavaScript templating syntax, that is used to replace variables that look like {{variable}} with the value assigned.

You can create your own set of block files in the src/ directory. The directory structure inside of templates/ is maintained when generated.

Additionally, you can create an assets/ directory that will be copied to the generated folder. Files in the assets directory will not be transformed.

To add an assetsPath update the module.exports in index.js with:

assetsPath: join( __dirname, "assets" ),

That's it.

Once all the files are in place, you can run them from a local directory, by passing in the directory path to the script

npx @wordpress/create-block --template ~/src/my-template-package

If you want to share your template package, publish it to NPM, and then anyone can run the create-block command to generate a block from your templates.

You can see my mkaz-block-template package as an example. It is published to NPM and you can see the source on GitHub at mkaz/mkaz-block-template

You can create a block with a RichText component using:

npx @wordpress/create-block YOUR-BLOCK-SLUG \
    --template mkaz-block-template

As above, you can also use any of the command-line parameters to override the defaults.

Working with NPM Modules

The most recent version of create-block script (v2.6.0) added support for local directories. Earlier versions only support NPM packages. Using NPM is a nice way to share with anyone, so still worthwhile to publish.

Here's a quick crash course for working with NPM if you aren't familiar.

  1. Create an account at NPM.
  2. On your local computer, create a directory with your files. The package.json file determines the name, version, and all the information for NPM. See package.json documentation.
  3. Login on your computer by running: npm login
  4. Publish by running: npm publish

That's it, be sure to publish each time you change your templates because the npx command will pull down from the external registry.

Summary

I hope you found this helpful, using templates with create-block is a little-known feature that I'd like to see adopted more. I think it could be really help with automating block creation and sharing starter templates.

Props to Gziolo, Fabian, and Jessica for all their work on developing these features.

Additional props to Ryan Welcher for adding support or Local Directories.