Overview
The blocklet.yml file is the central configuration manifest for any Blocklet. It's a YAML file that declares all the essential metadata and settings that Blocklet Server requires to discover, install, run, and manage your application. By defining your Blocklet's properties in a structured, declarative way, you ensure it is portable, self-contained, and seamlessly integrated into the ArcBlock ecosystem.
This document provides a high-level introduction to the purpose and structure of blocklet.yml. For a detailed breakdown of every available field, please see the Configuration Reference.
The Role of blocklet.yml#
The blocklet.yml file acts as a contract between your application and the Blocklet Server. It specifies everything from the application's name and version to its runtime requirements, network interfaces, and dependencies.
Here is a simplified diagram of how blocklet.yml fits into the development and deployment lifecycle:
Key Sections#
A blocklet.yml file is organized into several logical sections. Here are the primary groups of properties you will use:
Section | Description | Learn More |
|---|---|---|
Metadata | Core identity and descriptive information, including | |
Execution | Defines how your Blocklet's code is executed, including the runtime | |
Networking | Configures how your Blocklet is exposed to the network, including public | |
Dependencies | Declares system | |
Features | Enables and configures optional, built-in features such as custom | |
Publishing | Contains information used by a Blocklet Store, such as |
Example: A Minimal blocklet.yml#
Here is a look at a basic blocklet.yml file. It includes the minimum required fields to define a simple application.
# The human-readable name of the Blocklet. Used to generate the DID if not provided.
name: 'my-first-blocklet'
# The version of your Blocklet, following SemVer.
version: '0.1.0'
# The unique Decentralized Identifier (DID) for this Blocklet.
# If omitted, it's generated from the 'name' field during the first publish.
did: 'z8ia...'
# A short, plain-text description of what the Blocklet does.
description: 'A simple demonstration Blocklet.'
# The main executable file for the Blocklet.
main: 'blocklet.js'
# Information about the author.
author:
name: 'Jane Doe'
email: 'jane.doe@arcblock.io'
# Defines the primary web interface for users.
interfaces:
- type: 'web'
name: 'publicUrl'
path: '/'
protocol: 'http'
# Scripts for managing the Blocklet's lifecycle.
scripts:
dev: 'node blocklet.js'This simple example defines a Blocklet with a name, version, and a single web interface. The Blocklet Server uses this information to install the necessary dependencies and run the blocklet.js file.
Now that you have a high-level understanding of what blocklet.yml is and what it does, you're ready to create your own. Proceed to the next section to build and validate your first Blocklet configuration.
Next: Getting Started