Blocklet Specification (blocklet.yml)

The blocklet.yml file is the heart of every Blocklet. It's a YAML manifest that defines all the essential metadata about your application, serving as the single source of truth for the Blocklet Server and other tools in the ecosystem.

Think of it as the equivalent of package.json in the Node.js world, but expanded to encompass the full lifecycle and configuration of a decentralized application. It details everything from the Blocklet's identity and version to how it runs, what web interfaces it exposes, its dependencies on other Blocklets, and how it integrates with the user interface.

This specification is the definitive reference for every field available in blocklet.yml. Whether you are building a simple static website or a complex, multi-service application, a well-formed blocklet.yml is the first step to ensuring it runs correctly and predictably.

Basic Example#

Here is a minimal blocklet.yml file to illustrate its basic structure. Each field is explained in detail in the sections below.

# Core identity of the Blocklet
did: z8iZpA63mBCy9j82Vf9aL3a8u9b5c7d9e1f2
name: my-awesome-blocklet
version: 1.0.0

# Human-readable metadata
title: My Awesome Blocklet
description: A simple Blocklet to demonstrate the core concepts.

# How the Blocklet is executed
main: api/index.js

# How the Blocklet is exposed to the web
interfaces:
  - type: web
    name: publicUrl
    path: /
    prefix: '*'
    port: BLOCKLET_PORT
    protocol: http

# System requirements
requirements:
  server: ">=1.16.0"
  os: "*"

Specification Sections#

The blocklet.yml specification is organized into logical groups of properties. Explore the sections below for a comprehensive guide to each field, its purpose, and valid values.

Now that you have an overview of the blocklet.yml structure, dive into the specific sections above to find the details you need. For programmatic interaction with this metadata, see the API Reference.