Brick Runtime

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 (see

), 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:
  • 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 extensions from v2 to v3, we’d love to help! Contact us at support@pixiebrix.com

  • Page Editor: When you open an extension written with v2 in the Page Editor, the Page Editor will attempt to automatically convert it to a v3 extension. When you save the extension, the Page Editor will save the extension as a v3 extension.
  • 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 extension 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


  • Blueprints now support a definitions section that can contain inline extension point and reader definitions