bundle

The blocklet bundle command packages your blocklet project into a standardized, distributable format. This is a critical step before you can deploy your blocklet to a Blocklet Server instance or publish it to the Blocklet Store. The command gathers all necessary source code, assets, and metadata, and organizes them into a .blocklet directory within your project.

Depending on your blocklet's type and your specific needs, you can use different bundling modes to optimize the final package.

Before bundling, ensure your project is ready for distribution. For publishing, you might want to use the blocklet version command first. After bundling, the next step is typically to deploy or upload your blocklet.

Bundling Modes#

Blocklet CLI supports three distinct bundling modes: simple, zip, and compact. The CLI automatically selects a mode based on the group property in your blocklet.yml, but you can override this with command-line flags.

Simple Mode#

This is the default mode for most blocklets, especially those with a backend component (e.g., group: 'dapp' or group: 'gateway'). It performs a straightforward copy of your project files into the .blocklet build directory. It respects the files array in both your package.json and blocklet.yml to determine which files to include, using npm-packlist internally.

• Use Case: Best for Node.js services or dapps where dependencies are managed by a package manager and extensive client-side bundling is not required.
• To force: blocklet bundle --simple

Zip Mode#

This mode is automatically used for static blocklets or when the group is not defined. It bundles your main application code and any specified scripts into a compressed .zip archive named blocklet.zip inside the .blocklet directory. This is ideal for blocklets that are primarily front-end or have self-contained JavaScript logic.

• Use Case: Best for static websites, single-page applications, or blocklets with hook scripts that need to be packaged together.
• To force: blocklet bundle --zip

Compact Mode#

This is the most advanced mode, designed to produce the smallest and most efficient bundle possible. It bundles all JavaScript/TypeScript entry points (your main file and any hook scripts) into a single, minified file. This mode significantly reduces the number of files and the overall size of your blocklet, which can lead to faster deployments and improved performance.

• Use Case: Recommended for production builds where performance and size are critical. It's particularly effective for dapps with complex front-end and back-end logic that can be bundled together.
• To force: blocklet bundle --compact

Command Options#

Option	Description
--zip	Forces the bundler to use the zip mode.
--simple	Forces the bundler to use the simple mode.
--compact	Forces the bundler to use the compact mode for a smaller, optimized build.
--create-release	After bundling, creates a .tgz release package ready for publishing.
--create-archive	Used with --create-release to also generate a .zip archive of the bundle.
--changelog	Controls whether to include the changelog in the bundle. Defaults to true. Use --no-changelog to disable.
--source-map	Generates source maps for easier debugging in production. (Primarily for compact mode).
--nosources-source-map	Generates a source map but excludes the original source code content. (Primarily for compact mode).
--external <packages>	A comma-separated list of packages to exclude from the bundle. These are treated as external dependencies.
--external-manager <manager>	Specifies the package manager (e.g., npm, yarn) to use for handling external dependencies. Defaults to npm.
--store-url <url>	Specifies the Blocklet Store URL to use when parsing metadata. Overrides environment variables.
--minify	Controls whether to minify the output. Defaults to true in compact mode. Use --no-minify to disable.
--dependencies-depth <depth>	Sets the depth for resolving external dependencies. Defaults to 9.
--monorepo	Indicates that the blocklet is part of a monorepo, adjusting path resolution accordingly.

How It Works#

The bundling process follows a series of steps to ensure a consistent and valid blocklet package is created.

Examples#

Standard Bundle#

For a dapp or gateway blocklet, running the command without flags will use simple mode.

This creates a .blocklet directory containing all the necessary files from your project.

Compact Bundle with Externals#

To create a highly optimized production build, use --compact. If your blocklet depends on large libraries that you prefer to keep external, specify them with --external.

This will bundle your application code but leave react and react-dom as dependencies to be resolved at runtime.

Bundle and Create Release#

To bundle your blocklet and immediately package it into a .tgz file for distribution, use the --create-release flag.

After a successful bundle, this will generate a file like my-blocklet-1.0.0.tgz in your project's root directory, which you can then upload.

After successfully bundling your blocklet, you are ready for the next steps in the development lifecycle. You can either deploy it to a test server or upload it to a Blocklet Store.