Bundle Blocklet

The blocklet bundle command is the essential step for packaging your blocklet's source code, assets, and metadata into a single, deployable unit. This process prepares your blocklet for deployment to a Blocklet Server instance or for distribution via a blocklet store.

This command reads your blocklet.yml configuration, gathers all necessary files, and places them into a .blocklet/bundle directory within your project.

Bundling Modes#

The CLI offers several bundling modes. It automatically selects an appropriate mode based on your blocklet's group type, but you can also specify one manually. For most modern JavaScript/TypeScript blocklets, compact mode is recommended as it provides significant optimizations.

Mode	Description	Best For	Manual Flag
compact	(Recommended) Transpiles and bundles all JS/TS source code into a minimal set of files, with options for minification and source maps.	Most blocklets, especially DApps and services.	--compact
simple	Copies all necessary files into the bundle directory without any compilation or archiving. Ideal for Node.js based services.	gateway blocklets and simple services.	--simple
zip	Copies files and then creates a compressed .zip archive. This is the standard for static blocklets or when an archive is needed.	static blocklets, or when using --create-archive.	--zip

The Bundling Process#

The bundling process follows a clear sequence to ensure all dependencies and assets are correctly included.

What's Included in the Bundle?#

The bundler intelligently includes only the necessary files to run your blocklet, based on several sources:

• Metadata: Your blocklet.yml file and other meta files like blocklet.md.
• Main Entry: The file specified in the main property of blocklet.yml.
• NPM Files: Files included by default according to package.json's files field and .npmignore rules, determined by npm-packlist.
• Blocklet Files: Any additional files or glob patterns specified in the files array of your blocklet.yml.
• Scripts: JavaScript files referenced in your blocklet's lifecycle scripts (e.g., pre-start, post-start).
• Migrations: All scripts located in the migration/*.js directory.
• Specifications: api.yml (OpenAPI) and components.yml (Open Components) if they exist.
• Rewritten package.json: A minimal package.json is generated inside the bundle, containing only essential keys like name, version, description, and processed external dependencies.

Command Options#

You can customize the bundling process with the following options:

Option	Description
--compact	(Recommended) Activates the compact mode for advanced bundling.
--simple	Forces the bundler to use the simple mode.
--zip	Forces the bundler to use the zip mode.
--create-archive	Creates a compressed .zip archive of the final bundle directory.
--create-release	Creates a release asset after bundling (typically used in CI/CD pipelines).
--external <module>	Excludes the specified module from the bundle in compact mode. Can be used multiple times.
`--minify <true	false>`
--source-map	Generates a source map for the bundled code in compact mode, which is useful for debugging.
--no-changelog	Disables the inclusion of a changelog in the release.

Examples#

Recommended: Compact Mode with External Dependencies

When using a framework like React, you'll want to exclude it from your bundle and treat it as an external dependency. This is common when the blocklet will run in an environment where React is already provided.

Default Bundling

For a simple blocklet, running the command without arguments is sufficient. The CLI will choose an appropriate mode automatically.

Creating a Release Archive

To generate a .zip file ready for upload, use the --create-archive flag.

This will create a file like example-blocklet-1.0.0.zip in the .blocklet directory.

After successfully bundling your blocklet, the next step is to version and distribute it. You can learn more in the Manage Version section or proceed directly to Deploy Blocklet.