Create a Blocklet

Blocklet CLI provides two primary commands to start your project: blocklet init and blocklet create. Use init to turn an existing directory into a Blocklet, or create to scaffold a new project from an official template. Both commands help you configure the essential blocklet.yml metadata file.

After creation, your project will have a standard structure. To learn more about the files and directories involved, see the Project Structure documentation.

From Scratch: blocklet init#

The blocklet init command is designed to initialize a Blocklet in the current directory. It's the right choice when you have an existing project folder that you want to convert into a Blocklet. The command launches an interactive wizard to help you create the blocklet.yml file and other necessary assets.

Usage#

To start the interactive process, simply run the command in your project's root directory:

Options#

You can use options to streamline the process, for example, by skipping the interactive prompts or providing a pre-existing DID.

Option	Alias	Description
--yes	-y	Skips all interactive prompts and uses default values.
--force	-f	Same as --yes.
--did <did>		Specifies a pre-existing DID for the Blocklet, skipping the DID generation step.
--connect-url <url>		Provides a custom Blocklet Store or node URL for generating a new DID.
--monikers <monikers>		A utility flag that only generates a DID with the given moniker and then exits. It does not initialize a full project.

Interactive Prompts#

If you run blocklet init without the --yes flag, you'll be prompted for the following information:

• Blocklet Title: A human-readable title for your Blocklet.
• Description: A concise summary of what your Blocklet does.
• Group: The category of your Blocklet (e.g., dapp, static). This determines which boilerplate files are created.
• Main Entry Point: The primary file for your application (e.g., index.js for a dApp or . for a static site).

Based on your answers, blocklet init generates a blocklet.yml file and other boilerplate assets like blocklet.md, logo.png, and an entry file (index.js or index.html) if they don't already exist.

From a Template: blocklet create#

The blocklet create command scaffolds a new Blocklet project in a new directory using an official starter template. This is the recommended approach for starting a project from a clean slate, as it sets up a complete, runnable environment.

This command acts as a wrapper around the create-blocklet package, ensuring you always use the latest version of the scaffolding tool.

Usage#

To create a new Blocklet, provide a name for your project. A new directory with this name will be created.

Arguments & Options#

Name	Description
name	The name of your new Blocklet. A directory with this name will be created for your project.
--did <did>	Passes a pre-existing DID to the create-blocklet scaffolder.
--did-only	A utility flag that only generates a Blocklet DID and then exits. It does not create a project.

Example#

To create a new Blocklet named my-first-app, run:

This will trigger the create-blocklet interactive wizard, which will prompt you to choose from a list of official starter templates.

Generating a Blocklet DID#

A DID is a unique, decentralized identifier that serves as the identity of your Blocklet. Both init and create will guide you through generating a new DID using your DID Wallet if one isn't provided.

The process works by establishing a connection between the CLI and your wallet.

For automated workflows, you can generate a DID beforehand and supply it using the --did option. This avoids any interactive prompts from DID Wallet.

Now that you have created your Blocklet project, the next step is to run it in a local development environment. Learn how in the Develop a Blocklet guide.

For a detailed reference on all available options, see the command references for blocklet init and blocklet create.