Bundling

The blocklet bundle command is a crucial step in the development workflow that packages your blocklet project into a distributable format. This process ensures that all necessary code, assets, and metadata are correctly assembled for deployment on a Blocklet Server. The Blocklet CLI offers three distinct bundling modes—simple, zip, and compact—each tailored for different types of blocklets and use cases.

Understanding these modes is key to optimizing your blocklet's size, performance, and deployment process. Before diving into the details, you can also review the Development Workflow for a broader context.

How the Bundling Mode is Determined#

The CLI automatically selects a bundling mode based on your blocklet's configuration (blocklet.yml) and any command-line flags you provide. You can override the default behavior using flags like --simple, --zip, or --compact.

Here is a flowchart illustrating the decision logic:

Bundling Modes Explained#

Each mode serves a specific purpose. Let's explore them in detail.

Simple Mode#

The simple mode is the most straightforward. It prepares your blocklet for deployment by copying the necessary files into the .blocklet/bundle directory without compression or complex transformations.

• Use Case: Primarily for gateway blocklets or backend services where the source structure is already optimized for deployment and does not require bundling into a single file.
• Process: The command ensures the output directory (.blocklet/bundle) is clean, creates a blocklet.js entry file if a custom main is specified in blocklet.yml, and then generates the final blocklet.json metadata file.
• Output: A .blocklet/bundle directory that mirrors your project structure, ready to be run by Blocklet Server.

Zip Mode#

The zip mode is designed for blocklets that consist of static assets or include hook scripts. It packages the main application content into a single zip archive while keeping scripts accessible.

• Use Case: This is the default mode for static blocklets (e.g., a React or Vue single-page application) and can be forced with the --zip flag. It's ideal for distributing a collection of assets efficiently.
• Process:
• 1. It identifies the main entry point (e.g., index.html) and any hook scripts defined in blocklet.yml.
  2. The main content directory is compressed into a blocklet.zip file inside .blocklet/bundle.
  3. A primary blocklet.js entry file is created to point to the zipped content.
  4. If your blocklet includes hooks (e.g., pre-start), the CLI creates corresponding JavaScript wrappers in the bundle directory so Blocklet Server can execute them.
• Output: The .blocklet/bundle directory will contain blocklet.zip, blocklet.js, blocklet.json, and any generated hook entry files.

Compact Mode#

The compact mode is the most advanced option, designed to produce a highly optimized, minimal bundle. It uses a bundler to merge your code and dependencies into as few files as possible.

• Use Case: Best for complex DApps and backend blocklets where you want to reduce the bundle size, manage external dependencies, and improve startup performance.
• Process:
• 1. The command bundles your blocklet's main entry point, resolving and including local dependencies.
  2. It intelligently handles external dependencies. Instead of bundling packages from node_modules, it lists them in a package.json inside the .blocklet/bundle directory. Blocklet Server will then install these dependencies upon deployment.
  3. After bundling, it cleans up the output directory, removing any intermediate files that are not part of the final, compact bundle.
  4. It supports source maps for easier debugging in production.
• Output: A lean .blocklet/bundle directory containing the bundled application code (e.g., index.js), a blocklet.json file, and a package.json that specifies only the external dependencies required by your blocklet.

Managing External Dependencies#

In compact mode, you can control which dependencies are bundled and which are treated as external using the --external flag. An external dependency is not included in your bundle; instead, it's listed in the bundle's package.json for the target Blocklet Server to install.

• Specifying Externals: You can list packages by name:blocklet bundle --compact --external express --external lodash


• Externalizing All Dependencies: To externalize all dependencies listed in your project's package.json, use an asterisk:blocklet bundle --compact --external '*'



The CLI will find the correct versions for these packages from your project's package.json or node_modules and write them to the package.json in the .blocklet/bundle directory. You can also specify which package manager the target server should use with --external-manager <npm|pnpm|yarn>.

Comparison of Modes#

Feature	Simple Mode	Zip Mode	Compact Mode
Primary Use Case	Gateway blocklets, simple services	Static sites, blocklets with hooks	Complex DApps, backend services
Output Format	Directory of files	Directory with a .zip archive	Directory with bundled JS files
Dependency Handling	Dependencies are assumed to be present	Dependencies are bundled in the zip	Bundles local code, externalizes Node.js dependencies
Optimization	None	Compression for static assets	Code bundling, tree-shaking, minification
When to Use	When no build step is needed.	For distributing static websites or assets.	To create a small, optimized, and portable bundle.

By choosing the right bundling mode, you can ensure your blocklet is packaged efficiently for deployment. After bundling, the next logical step is to publish your blocklet.

Next, learn how to Publish a Blocklet to a Blocklet Store.