Develop a Blocklet

The blocklet dev command is the cornerstone of the local development workflow. It connects your local source code to a running Blocklet Server, enabling a live development session with features like log streaming and automatic cleanup. This guide will walk you through its usage and key features.

Before you begin, ensure you have followed the Getting Started guide to install the CLI and run a local Blocklet Server. If you haven't created a blocklet project yet, see Create a Blocklet.

The Core Development Workflow#

At its simplest, running blocklet dev from your project's root directory will install, start, and connect you to your blocklet in a development mode.

Here’s a breakdown of what happens when you run the command:

This entire process ensures that your development environment is self-contained and leaves no artifacts on the server after you're done.

Basic Usage#

To start a development session, navigate to your blocklet's directory and run:

The CLI will output the URL where you can access your running blocklet. Any logs generated by your blocklet will appear in your terminal.

Auto-opening in Browser#

You can add the --open flag to automatically open the blocklet's URL in your default browser once it's running.

Developing a Component within an Application#

Blocklets are often designed as components that run within a parent application. The dev command supports this workflow using the --app-did and --mount-point options.

Option	Description
--app-did <did>	The DID of the existing parent application where this component should be installed for development. You can also set this using the BLOCKLET_DEV_APP_DID environment variable.
--mount-point <path>	The URL path where the component will be mounted within the parent application (e.g., /my-component). You can also set this using the BLOCKLET_DEV_MOUNT_POINT environment variable.

For example, to develop a component and mount it at /profile inside a parent application, you would run:

Managing the Development Session#

The blocklet dev command also comes with several sub-commands to manage the state of your development blocklet without stopping the session.

• Resetting Data (reset) If you need to clear all data and configuration for your development blocklet and start fresh, use the reset subcommand. This is useful for testing initial setup flows.blocklet dev reset


• Claiming Test Tokens (faucet) For blocklets that interact with a blockchain, you may need test tokens. The faucet subcommand helps you claim tokens from a configured faucet.blocklet dev faucet --token TBA


• Removing the Blocklet (remove) While cleanup is automatic on exit, you can also manually remove the development blocklet from the server using the remove command.blocklet dev remove



Development in GitHub Codespaces#

The CLI has built-in support for GitHub Codespaces. When blocklet dev is run in a Codespaces environment, it automatically:

1. Adds the necessary routing rules to the default site on your Blocklet Server.
2. Configures the domain alias for the Codespace.
3. Provides you with the correct public URL to access your blocklet.

This streamlines the setup process, allowing you to start developing immediately without manual configuration.

With the dev command, you can efficiently code, test, and debug your blocklet in a live environment. Once your blocklet is working as expected, the next step is to package and distribute it. Proceed to the Publish a Blocklet guide to learn more.