Skip to main content

Block boilerplate

There is a boilerplate available for developing custom blocks that you want to publish as package on a registry (like npm). This boilerplate allows you to build the builder part of your block in the folder ./src/builder and the base class of the runner part (that contains all the non-UI-related code of a block) in the folder ./src/runner.

This boilerplate has the same package structure as the packages of the stock blocks. The idea behind it is to maximize code reusability. All the block code not specific for a particular runner UI should be in the package. Runners can then use these block packages and only have to implement the UI rendering (that is specific for a runner) for each block.

🚀 Get started

To use the boilerplate, follow these steps:

  1. Download or clone the repository to your local machine:
git clone https://gitlab.com/tripetto/blocks/boilerplate.git
  1. Run npm install inside the downloaded/cloned folder:
npm install
  1. Start the builder and load the block in developer (test) mode:
npm test

This command starts the local builder server and tries to open the URL http://localhost:3333 in your default browser. If no browser opens, open the browser and navigate to this URL. By default, the builder loads the form definition located at ./tests/example.json.

Next, open your favorite code editor/IDE and start working on your block. When a source code change is detected, the block should automatically recompile, and the builder in the browser should refresh.

📦 Publish your block

When your block is ready to share with the world, you may want to publish it. Make sure to update the name and description in package.json before doing so. Also, set the private property to false (currently, it is set to true to preserve unwanted publication).

Next, run the following command to increment the package version number, do a production build and publish the package to the npm registry.

danger

Make sure to replace the README.md file of the boilerplate with your own version. Also, update the package name and description in package.json before publishing it!

npm run publish:patch

🌎 Translations

Tripetto uses the GNU gettext system. If you want to create translations for your block, you first need to generate the POT file for it. Run the following command to do so:

npm run pot

This generates a file template.pot in the translations folder of your block. Use that file to translate your block (for example, using POEdit), and then store the translations in the translations folder.