Overview
The @blocklet/meta library is a foundational package within the Blocklet ecosystem. It provides the tools to define, parse, validate, and manage the metadata for any Blocklet. This library serves two primary functions: it establishes the formal specification for the blocklet.yml manifest file and offers a comprehensive set of utility functions for interacting with Blocklet metadata and runtime state programmatically.
The blocklet.yml Specification#
The blocklet.yml file is the central manifest for a Blocklet, analogous to package.json in a Node.js project. It's a declarative YAML file that defines everything about the Blocklet. The formal schema, defined using the Joi validation library, ensures that all Blocklets across the ecosystem are structured consistently, enabling interoperability between Blocklet Server, registries, and developer tools.
Key sections of the specification include:
Core Metadata
The Blocklet's unique identifier (did), name, version, title, and description.
Execution & Environment
How the Blocklet runs, specified by its engine, runtime requirements, lifecycle scripts, and environment variables.
Interfaces & Services
How the Blocklet exposes itself to the web and other services, defining UIs, API endpoints, and service ports.
Composition
How a Blocklet is built from other Blocklets (components), enabling complex, modular applications.
UI & Theming
Definitions for navigation entries and theme properties that integrate the Blocklet's UI into the broader user experience.
Monetization & Security
Pricing rules, revenue-sharing configurations, and cryptographic signatures to ensure metadata integrity.
The Utility Library#
Beyond the specification, @blocklet/meta exports a rich set of JavaScript/TypeScript functions for developers and tools to work with Blocklet metadata and state. These utilities provide the core logic for the Blocklet Command Line Interface (CLI) and Blocklet Server, handling tasks from installation and dependency resolution to runtime configuration and state management.
Category | Key Functions | Description |
|---|---|---|
Parsing & Validation |
| Read, fix, and validate |
Component & State |
| Traverse component trees, find specific components, and inspect runtime statuses. |
DID & Wallet |
| Generate Blocklet-specific Decentralized Identifiers (DIDs) and manage associated wallets. |
Security |
| Perform cryptographic operations like signing and verifying data to ensure authenticity. |
File System |
| Programmatically find and manipulate |
Whether you are developing a new Blocklet, building tools for the ecosystem, or integrating Blocklet capabilities into your platform, the @blocklet/meta library is your starting point. Begin by exploring the Getting Started guide to parse your first blocklet.yml file.