Composition (Components)

Blocklets can be composed of other blocklets, creating modular and powerful applications. This composition is managed through the components property in blocklet.yml, which allows you to define other blocklets as dependencies.

The runtime environment uses this information to build a dependency tree, ensuring that all required components are installed and running before the parent blocklet starts. This enables the creation of complex applications from smaller, single-purpose, and reusable parts.

The components Property#

The components property is a top-level key in blocklet.yml that accepts an array of component objects. Each object in the array defines a child blocklet that the current blocklet depends on.

Component Object Schema#

Each object within the components array defines a single dependency and its configuration.

Field	Type	Required	Description
source	object	Yes	Defines where to fetch the component blocklet from. See source property details below.
required	boolean	No	If true, the parent blocklet cannot start if this component fails to install or start. Defaults to false.
title	string	No	A suggested title for the component instance when presented to the user. The user can override this during setup.
description	string	No	A suggested description for the component instance.
mountPoint	string	No	A suggested mount point (URL path) for the component instance.

The source Property#

The source object is mandatory for each component and specifies its origin. It can be configured in two primary ways: sourcing from a URL or sourcing from a Blocklet Store.

Sourcing from a Blocklet Store#

This is the recommended method, as it leverages a registry for versioning, discovery, and management.

Field	Type	Required	Description
store	string	Yes	The URI of the blocklet store or registry.
name	string	Yes	The name of the component blocklet in the store.
version	string	No	A semantic version range (e.g., ^1.2.0, 2.x) or the tag latest. Defaults to latest.

Example:

Sourcing from a URL#

This method allows you to specify a direct URL to a component's distributable package. This is useful for development, private components, or when a Blocklet Store is not available.

Field	Type	Required	Description
url	string or string[]	Yes	A direct URI to the component's tarball. An array of URIs can be provided for fallback purposes.
version	string	No	A semantic version range (e.g., ~2.0.x) to constrain the component version. The runtime will verify if the component at the URL satisfies this range.

Example:

Full components Example#

Here is a complete example demonstrating how to define multiple components with different sources and requirements.

After defining how your blocklet is composed of other blocklets, the next step is to configure its own contributions to the user interface. Proceed to the UI & Theming section to learn about the navigation and theme properties.