Configuration Reference

Features

Your Blocklet can leverage a range of built-in features provided by Blocklet Server to enhance functionality, security, and user experience. This section details how to enable and configure optional features such as custom capabilities, authentication, navigation, theming, resource sharing, and custom events directly within your blocklet.yml file.
Capabilities#The capabilities object is a collection of boolean flags that declare the supported features and operational modes of your Blocklet. These settings inform Blocklet Server how to manage and integrate your component.
name: my-feature-rich-blocklet
did: z8iZpkyb3tpp1kF1aB1f123456789abcdef
version: 1.0.0
description: A blocklet demonstrating various features.
capabilities:
  clusterMode: false
  didSpace: 'owner'
  navigation: true
  serverless: false
  component: true
  sitemap: true
  mcp: falseKey
Type
Description
clusterMode
boolean
Indicates if the Blocklet is designed to run in a multi-instance, clustered environment.
didSpace
string
Specifies the DID Space requirement. Valid values are owner or child, defining its relationship with the parent space.
navigation
boolean
If true (the default), this Blocklet's navigation entries will be automatically merged into the main UI.
serverless
boolean
Specifies if the Blocklet is compatible with serverless deployment environments.
component
boolean
If true, this Blocklet can be installed and used as a component by other Blocklets.
sitemap
boolean
Indicates that the Blocklet supports a composable sitemap.
mcp
boolean
Indicates that the Blocklet supports the MCP server sitemap.
Authentication#Blocklet Server provides a built-in authentication service that you can configure for any of your web interfaces. To enable it, add an auth service to an interface's services array and specify its configuration.
interfaces:
  - type: 'web'
    name: 'publicUrl'
    path: '/'
    prefix: '*'
    services:
      - name: 'auth'
        config:
          whoCanAccess: 'invited'
          blockUnauthenticated: true
          allowSwitchProfile: true
          ignoreUrls:
            - '/api/public/*'
            - '/assets/*'Configuration Options (config):
Key
Type
Description
whoCanAccess
string
Defines access control. Options: 'owner' (only the DID Space owner), 'invited' (owner and invited users), or 'all' (any authenticated user).
blockUnauthenticated
boolean
If true, any request from a user who is not logged in will be blocked, except for paths listed in ignoreUrls.
blockUnauthorized
boolean
If true, access is denied for users who are authenticated but do not meet the whoCanAccess criteria.
allowSwitchProfile
boolean
If true, allows users to switch between different profiles or DIDs within your Blocklet.
ignoreUrls
string[]
An array of URL patterns that are exempt from authentication checks.
profileFields
string[]
Deprecated. Defines which user profile fields your Blocklet requires.
Navigation#The navigation field allows your Blocklet to add entries to the Blocklet Server's main navigation menu, creating a seamless user experience. You can define a hierarchy of links, complete with icons, roles, and internationalization.
navigation:
  - id: 'home'
    title: 'Home'
    link: '/'
    icon: 'home'
    role: ['owner', 'guest']
  - id: 'settings'
    title: 'Settings'
    icon: 'cog'
    items:
      - title: 'Profile'
        link: '/settings/profile'
        role: ['owner']
      - title: 'Billing'
        link: '/settings/billing'
        role: ['owner']
  - id: 'docs'
    title: 'Documentation'
    link: 'https://docs.arcblock.io'
    visible: trueNavigation Item Properties:
Key
Type
Description
id
string
A unique identifier for the navigation item, following JavaScript variable naming rules.
title
string or object
The text displayed for the menu item. Can be a string or a key-value object for localization (e.g., en: 'Home', zh: '首页'). Required.
description
string or object
A tooltip or description for the menu item. Can also be localized.
link
string or object
The destination URL. Can be a relative path (e.g., /profile) or an absolute URL. Can also be localized.
component
string
The name of a component Blocklet that provides the content for this navigation item.
section
string[]
Assigns the item to a specific navigation section.
role
string[]
An array of user roles that can see this item (e.g., owner, guest).
icon
string
The name of an icon to display next to the title.
visible
boolean
Controls the visibility of the navigation item.
items
NavigationItem[]
An array of nested navigation items to create submenus.
Theming#The theme object allows you to specify basic visual styles for your Blocklet to better integrate with the overall UI.
theme:
  background:
    header: '#FFFFFF'
    footer: '#F8F8F8'
    default: '#FAFAFA'Key
Type
Description
background
string or object
Sets the background color. It can be a single string for the entire Blocklet or an object specifying colors for header, footer, and default areas.
Resource Sharing#The resource object enables your Blocklet to define and export data bundles that other Blocklets can consume. This is useful for sharing configurations, assets, or other structured data.
resource:
  types:
    - type: 'site.config'
      description: 'General site configuration'
  bundles:
    - did: 'z2qa...'
      type: 'site.config'
      public: trueKey
Type
Description
types
object[]
An array defining the kinds of resources the Blocklet provides. Each object has a type (a unique string identifier) and a description.
bundles
object[]
An array of the actual resource bundles being shared. Each object has a did (the resource's DID), type (matching a defined type), and a public flag.
Custom Events#Declare the custom events your Blocklet can emit. This allows other services or Blocklets within the system to subscribe and react to these events, creating powerful, loosely-coupled integrations.
events:
  - type: 'post.published'
    description: 'Triggered when a new post is published.'
  - type: 'user.registered'
    description: 'Triggered when a new user completes registration.'Event Properties:
Key
Type
Description
type
string
A unique event name, typically in noun.verb format (e.g., post.published). The blocklet. prefix is reserved. Must be between 1 and 128 characters.
description
string
A clear, human-readable explanation of what the event signifies. Must be between 1 and 256 characters.

By leveraging these features, you can significantly enhance your Blocklet's integration and functionality. Once you have configured these options, you can proceed to prepare your Blocklet for distribution. To learn more, see the Publishing guide.

Key	Type	Description
`clusterMode`	`boolean`	Indicates if the Blocklet is designed to run in a multi-instance, clustered environment.
`didSpace`	`string`	Specifies the DID Space requirement. Valid values are `owner` or `child`, defining its relationship with the parent space.
`navigation`	`boolean`	If `true` (the default), this Blocklet's `navigation` entries will be automatically merged into the main UI.
`serverless`	`boolean`	Specifies if the Blocklet is compatible with serverless deployment environments.
`component`	`boolean`	If `true`, this Blocklet can be installed and used as a component by other Blocklets.
`sitemap`	`boolean`	Indicates that the Blocklet supports a composable sitemap.
`mcp`	`boolean`	Indicates that the Blocklet supports the MCP server sitemap.

Key	Type	Description
`whoCanAccess`	`string`	Defines access control. Options: `'owner'` (only the DID Space owner), `'invited'` (owner and invited users), or `'all'` (any authenticated user).
`blockUnauthenticated`	`boolean`	If `true`, any request from a user who is not logged in will be blocked, except for paths listed in `ignoreUrls`.
`blockUnauthorized`	`boolean`	If `true`, access is denied for users who are authenticated but do not meet the `whoCanAccess` criteria.
`allowSwitchProfile`	`boolean`	If `true`, allows users to switch between different profiles or DIDs within your Blocklet.
`ignoreUrls`	`string[]`	An array of URL patterns that are exempt from authentication checks.
`profileFields`	`string[]`	Deprecated. Defines which user profile fields your Blocklet requires.

Key	Type	Description
`id`	`string`	A unique identifier for the navigation item, following JavaScript variable naming rules.
`title`	`string` or `object`	The text displayed for the menu item. Can be a string or a key-value object for localization (e.g., `en: 'Home', zh: '首页'`). Required.
`description`	`string` or `object`	A tooltip or description for the menu item. Can also be localized.
`link`	`string` or `object`	The destination URL. Can be a relative path (e.g., `/profile`) or an absolute URL. Can also be localized.
`component`	`string`	The name of a component Blocklet that provides the content for this navigation item.
`section`	`string[]`	Assigns the item to a specific navigation section.
`role`	`string[]`	An array of user roles that can see this item (e.g., `owner`, `guest`).
`icon`	`string`	The name of an icon to display next to the title.
`visible`	`boolean`	Controls the visibility of the navigation item.
`items`	`NavigationItem[]`	An array of nested navigation items to create submenus.

Key	Type	Description
`types`	`object[]`	An array defining the kinds of resources the Blocklet provides. Each object has a `type` (a unique string identifier) and a `description`.
`bundles`	`object[]`	An array of the actual resource bundles being shared. Each object has a `did` (the resource's DID), `type` (matching a defined type), and a `public` flag.

Key	Type	Description
`type`	`string`	A unique event name, typically in `noun.verb` format (e.g., `post.published`). The `blocklet.` prefix is reserved. Must be between 1 and 128 characters.
`description`	`string`	A clear, human-readable explanation of what the event signifies. Must be between 1 and 256 characters.

Overview

Getting Started

Configuration Reference

Features

Capabilities#

Authentication#

Navigation#

Theming#

Custom Events#

Dependencies

Publishing