Make your own create-block templates

Published on:
Category: WordPress

Did you know the create-block script can support templates? The templates allows you to create your own files to be generated for a new block. I can see this being quite useful especially if you are an agency or business that creates many custom blocks, or just 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 for values to enter 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 templates so the blocks generated match a starting point of your choice. The create-block tool supports external templates hosted as NPM packages. The package consists of a 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 will probably also 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, the only real use here is replacing variables that look like {{variable}} with the value assigned.

You can then create your 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 directly 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 and published to NPM, you can then run the create-block command and it will use your templates and create a block.

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

Right now the create-block script only works with external templates hosted on NPM. I’ve opened a ticket to support local directories, but for now you’ll need to create and publish to npm. It is relatively easy, here’s a quick crash course 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, the create-block templating is a relatively unknown 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.

Leave a Reply