Getting Started
This guide will walk you through creating a minimal blocklet.yml file for a basic web application. The blocklet.yml file is the manifest for your Blocklet, defining everything from its name and description to how it runs and what network interfaces it exposes.
Before you begin, you might want to read the Overview for a high-level understanding of the file's purpose and structure.
1. Minimal Configuration#
Every Blocklet needs a core set of identifiers. Let's start by creating a blocklet.yml file in the root of your project with the minimum required fields.
name: my-first-blocklet
version: 0.1.0
description: A brief description of my first Blocklet.
did: z8iZpA93h3yVW2y9cK12i2yQ5b6c8a5d3f2e1g4hHere's what each of these fields means:
Field | Description |
|---|---|
| A unique, human-readable identifier for your Blocklet. It's used to derive the Blocklet's DID. |
| The version of your Blocklet, which must follow Semantic Versioning (e.g., |
| A short summary of what your Blocklet does. It must be between 3 and 160 characters. |
| The Decentralized Identifier for the Blocklet. Blocklet Server uses the |
2. Defining the Entry Point#
Now, we need to tell Blocklet Server how to start your application. This is done using the main field, which specifies the entry script.
Let's assume your application's entry point is a file named app.js in a dist folder.
name: my-first-blocklet
version: 0.1.0
description: A brief description of my first Blocklet.
did: z8iZpA93h3yVW2y9cK12i2yQ5b6c8a5d3f2e1g4h
main: dist/app.js3. Exposing a Web Interface#
To make your application accessible from a web browser, you need to define an interface. The interfaces field allows you to declare one or more ways to access your Blocklet.
For a standard web application, you'll define an interface of type web.
name: my-first-blocklet
version: 0.1.0
description: A brief description of my first Blocklet.
did: z8iZpA93h3yVW2y9cK12i2yQ5b6c8a5d3f2e1g4h
main: dist/app.js
interfaces:
- type: web
name: publicUrl
path: /
protocol: http
port: BLOCKLET_PORTLet's break down the interface configuration:
Field | Value | Description |
|---|---|---|
|
| Declares this as a primary web interface. A Blocklet can only have one |
|
| A human-readable name for this interface. |
|
| The root path within the Blocklet that this interface serves. |
|
| The protocol used by the interface. Defaults to |
|
| Specifies the environment variable that will contain the port number your application should listen on. Blocklet Server assigns a port at runtime and exposes it through this variable. Your application code must read |
Your application code (dist/app.js) should look something like this to correctly use the port:
const http = require('http');
// The port is supplied by Blocklet Server via this environment variable
const port = process.env.BLOCKLET_PORT || 3000;
const server = http.createServer((req, res) => {
res.statusCode = 200;
res.setHeader('Content-Type', 'text/plain');
res.end('Hello from My First Blocklet!\n');
});
server.listen(port, () => {
console.log(`Server running at http://localhost:${port}/`);
});4. Validating the Configuration#
With your blocklet.yml created, you can easily validate it. The Blocklet CLI automatically checks this file's syntax and requirements whenever you run commands like blocklet dev or blocklet bundle.
If there is an error, the CLI will provide a descriptive message. For example, if you forget the description field, you might see an error like this:
Error: "description" is required in blocklet.ymlA successful validation will allow the command to proceed without any configuration errors.
Next Steps#
You now have a valid, minimal blocklet.yml that defines a runnable web application. This is the foundation for building more complex Blocklets.
To learn about all the available fields and advanced configurations, such as adding environment variables, dependencies, and publishing information, proceed to the Configuration Reference.