Develop Mode

The blocklet dev command is the core of the local development workflow. It connects your local blocklet project to a running Blocklet Server instance, allowing you to test and iterate in a realistic environment with live updates, log streaming, and automatic cleanup.

Core Workflow#

Running the command in your blocklet's root directory initiates a development session. This process automates installation, execution, and cleanup, streamlining the code-test-debug cycle.

Usage Scenarios#

Developing a Standalone Application#

For blocklets designed to run on their own, the basic command is all you need. It installs the blocklet as a new, standalone application on your Blocklet Server.

Developing as a Component#

Often, a blocklet is designed to run as a component inside a larger application. To simulate this, you can use the --app-did and --mount-point options to install your local blocklet into an existing application on your server.

• --app-did: The DID of the existing application to install into.
• --mount-point: The URL path where your component will be accessible (e.g., https://<app-url>/my-component).

Alternatively, you can configure these settings using environment variables: BLOCKLET_DEV_APP_DID and BLOCKLET_DEV_MOUNT_POINT.

Commands and Options#

The blocklet dev command includes several subcommands to manage the development lifecycle.

Command	Description
blocklet dev	The default action. Installs and starts the blocklet in development mode.
blocklet dev install	Installs the blocklet in development mode but does not start it.
blocklet dev remove	Removes a previously installed development mode blocklet.
blocklet dev reset	Resets the data and state of the development blocklet without a full reinstall.
blocklet dev faucet	Funds the development blocklet's wallet with test tokens from a configured faucet. Requires --token and --host flags.
blocklet dev studio	Opens the Blocklet Studio for the application, creating and installing it if necessary.

Common Flags#

These flags can be used with the blocklet dev command to modify its behavior.

Flag	Alias	Description
--open		Automatically opens the blocklet's URL in your default browser after it starts.
--app-did <did>	--app-id <did>	Mounts the blocklet as a component within the specified application DID.
--mount-point <path>		Sets the URL path for the component when mounted in an app. Required when using --app-did.
--store-url <url>		Specifies a default Blocklet Store URL for resolving component dependencies. Can also be set with the COMPONENT_STORE_URL environment variable.
--start-all-components		When developing a component, this flag also starts all other components within the parent application, creating a more realistic integration environment.
--e2e		Starts the blocklet in end-to-end test mode.

Developing in GitHub Codespaces#

The CLI includes built-in support for GitHub Codespaces. When a Codespaces environment is detected, blocklet dev automatically handles:

• Adding routing rules to the default site.
• Setting up a domain alias for the Codespaces URL.
• Providing a publicly accessible URL for your running blocklet.

This simplifies the setup process, allowing you to start developing immediately in a cloud environment. For more details, refer to the GitHub Codespaces development guide.

After developing your blocklet locally, the next step is to prepare it for distribution. Learn how to package your project in the Bundle Blocklet guide.