Execution & Environment

This section of the blocklet.yml file defines how a blocklet runs, its dependencies on the underlying system, and how it can be configured at runtime. Properly configuring these fields is essential for ensuring your blocklet is reliable, portable, and easy for users to manage.

Key areas of configuration include:

• engine: Specifies the runtime interpreter or binary used to execute the blocklet.
• docker: Defines settings for running the blocklet as a Docker container.
• requirements: Lists the system-level dependencies, such as ABT Node version, OS, and CPU architecture.
• environments: Declares environment variables that the blocklet uses for configuration.
• scripts: Defines lifecycle hooks that run at different stages, such as installation or startup.
• timeout: Sets time limits for startup and script execution to prevent hangs.

engine#

The engine field specifies how the blocklet's code should be executed. It can be a single object or an array of objects to support multiple platforms.

Property	Type	Description
platform	string	Optional. Specifies the target OS platform (e.g., linux, darwin, win32). Required if engine is an array.
interpreter	string	The runtime to use. Can be node (default), binary, blocklet, or bun.
source	string or object	Specifies where to find the engine's code. Can be an empty string (to use the main field), a URL, or an object pointing to another blocklet in a store.
args	string[]	Optional. An array of command-line arguments to pass to the interpreter. Defaults to [].

Example: Basic Node.js Engine

This configuration uses the node interpreter and points to the main field for the entry file.

Example: Platform-Specific Binaries

This example provides different binaries for macOS (darwin) and Linux.

Example: Using another Blocklet as an Engine

This delegates execution to another blocklet, fetched from a specified store. This is common for static site generators or other reusable runtimes.

docker#

For blocklets that are distributed as Docker containers, the docker field provides the necessary configuration. This field is mutually exclusive with engine and main.

Property	Type	Description
image	string	The name of the Docker image (e.g., nginx:latest). Required if dockerfile is not present.
dockerfile	string	The path to the Dockerfile within the blocklet bundle. Required if image is not present.
network	string	The Docker network mode.

Example: Using a Public Docker Image

Note: If you specify a dockerfile, you must also include it in the files array to ensure it's included in the blocklet bundle.

requirements#

This object specifies the minimum system requirements needed to install and run the blocklet, preventing installation on incompatible environments.

Property	Type	Description
abtnode	string	A valid SemVer range for the required ABT Node version.
server	string	A valid SemVer range for the required Blocklet Server version. Defaults to the latest stable version.
os	string or string[]	The compatible operating system(s) (e.g., linux, darwin). * allows any.
cpu	string or string[]	The compatible CPU architecture(s) (e.g., x64, arm64). * allows any.
nodejs	string	A valid SemVer range for the required Node.js version. * allows any.
fuels	object[]	An array of objects specifying required on-chain assets (tokens).

Example: Specifying System Requirements

environments#

This array defines the environment variables that the blocklet requires for configuration. These are presented to the user during installation and can be updated later.

Property	Type	Description
name	string	The variable name. Must be a valid variable name and cannot start with BLOCKLET_, COMPONENT_, or ABTNODE_. Required.
description	string	A human-readable description of what the variable is for. Required.
default	string	A default value for the variable. Cannot be used if secure is true.
required	boolean	Whether the user must provide a value. Defaults to false.
secure	boolean	If true, the value is treated as a secret and is not displayed in the UI after being set. Defaults to false.
validation	string	A regex string to validate the user's input.
shared	boolean	If true, this variable can be shared among components. Defaults to false if secure is true, otherwise determined by context.

Example: Defining Environment Variables

scripts#

Scripts define commands that are executed at specific points in the blocklet's lifecycle.

Hook	Execution Point
preFlight	Before installation or upgrade, used for preliminary checks.
preInstall	Before the blocklet's dependencies are installed.
postInstall	After the blocklet's dependencies are installed.
preStart	Before the blocklet's main process is started.
postStart	After the blocklet's main process has successfully started.
preStop	Before the blocklet's main process is stopped.
preUninstall	Before the blocklet is uninstalled.
preConfig	Before the blocklet's configuration is updated.

Example: Database Migration Script

This example runs a database migration script before the application starts.

timeout#

This object configures time limits for potentially long-running operations to prevent the blocklet from getting stuck.

Property	Type	Description
start	number	The maximum time in seconds to wait for the blocklet to start successfully. Min: 10, Max: 600. Defaults to 60.
script	number	The maximum time in seconds to allow any lifecycle script to run. Min: 1, Max: 1800.

Example: Setting Custom Timeouts

This section provides the foundation for running your blocklet. For details on how to expose it to the web, see the Interfaces & Services documentation.