Debug Blocklet

The blocklet debug command is a utility for developers to set environment variables on a running blocklet, primarily for enabling detailed logging and other debugging features without needing to rebuild or redeploy.

This command directly interacts with the Blocklet Server to modify a blocklet's configuration on the fly.

Command Usage#

The basic syntax for the command is as follows:

Basic Syntax

blocklet debug <value> --appId <did>

Prerequisites#

Before using this command, ensure that your Blocklet Server is running. If the server is not active, the command will fail. You can start the server using:

Start Server

blocklet server start

Arguments and Options#

value
string
required

The value to set for the DEBUG environment variable. It can also be a special command or a URL for advanced actions.

--appId <did>
string
required
The decentralized identifier (DID) of the specific blocklet you wish to debug.

How It Works#

The primary function of this command is to set a configuration entry with the key DEBUG for the specified blocklet. Many Node.js libraries, most notably the debug package, use the DEBUG environment variable to control which logging messages are sent to the console. By setting this value, you can enable verbose output from your blocklet and its dependencies.

Examples#

1. Enable All Debug Logs

To see all debug messages from a blocklet and its dependencies, use the wildcard * character.

Enable all debug logs

blocklet debug '*' --appId z2qa...w3k

After running this, you can view the blocklet's logs to see the detailed output.

2. Enable Specific Debug Logs

To target logs from a specific part of your application, you can provide a more specific namespace.

Enable logs for API routes

blocklet debug 'api:*' --appId z2qa...w3k

3. Disable Debug Logs

To turn off the debug logs, simply provide an empty string as the value.

Disable all debug logs

blocklet debug '' --appId z2qa...w3k

Advanced Actions#

The value argument also accepts special commands to perform specific actions on the blocklet, which can be useful during a debugging session.

Stop the Blocklet

To temporarily stop a running blocklet, use the `$stopBlocklet` value. This is useful if you need to attach a debugger or make changes that require a restart.

Set a Custom Store URL

If you need the blocklet to resolve components from a different blocklet store (e.g., a local development store), you can provide a URL as the value.

Stop Blocklet Example#

Stop a running blocklet

blocklet debug '$stopBlocklet' --appId z2qa...w3k

Set Custom Store Example#

Point blocklet to a local store

blocklet debug http://localhost:3030 --appId z2qa...w3k

After setting a custom store, the blocklet will fetch components from that URL, allowing you to test interactions with unpublished or development-stage components.


Once you have configured debugging, you may want to execute a specific script within the blocklet's context. To learn how, proceed to the Execute Script documentation.

Execute Script
Component Management