Advanced: Brick Runtime

The Brick Runtime controls how PixieBrix executes bricks, including: passing information between bricks, error handling, and logging.

Whenever we introduce a non-backward compatible change to the runtime, we increment the brick runtime apiVersion field, e.g., v1, v2, v3.

We maintain support for bricks written with old versions of the runtime. Bricks built with different versions of the runtime can be used together.

Specifying the runtime in YAML Brick Definitions

When using YAML-based configuration, the runtime is controlled via the apiVersion directive:

apiVersion: v3

For backward compatibility, apiVersion defaults to v1.

Runtime v3: Release 1.5.0

Runtime v3 introduces the following backward-incompatible changes:

• Support for field-level templates/expressions: !var, !nunjucks, !mustache

• A !pipeline and !defer expression boundaries (for use in the Document Builder)

• Drops support for the brick-level templateEngine directive (the directive is ignored)

• Templates are no longer auto-escaped (because HTML is sanitized prior to rendering). To escape a template:

  • Nunjucks: use the escape filter

• Support for the Handlebars template engine has been dropped

Page Editor changes:

• Nunjucks replaces Mustache as the default template engine

• Each field has a toggle to control how to pass data to

Migrating from v2 to v3

If you’d like assistance migrating your mods from v2 to v3, we’d love to help! Contact us at [email protected]

• Page Editor: When you open a mod written with v2 in the Page Editor, the Page Editor will attempt to convert it automatically to a v3 mod. When you save the mod, the Page Editor will save the mod as a v3 mod.

• Workshop:

  • Update the API version directive for the brick: apiVersion: v3

  • Update each template and variable expression to use !var, !mustache, or !nunjucks

Migrating from v1 to v3

• To migrate an mod from v1 to v3, you must use the workshop

Runtime v2: Release 1.4.0

Runtime v2 introduces the following backward-incompatible changes:

• Bricks must reference data by @inputor @outputKey. Data no longer flows implicitly from one brick to the next

Enhancements:

• Mods now support a definitions section that can contain inline starter brick and reader definitions