Skip to content

Home

Jump to bottom
TECHHAMARA edited this page Jun 5, 2026 · 1 revision

📖 Bolt CLI - Official Developer Wiki & Documentation

Welcome to the official developer wiki for Bolt CLI, the high-performance extension builder for MIT App Inventor 2. This wiki serves as a deep architectural guide, complete configuration reference, and best-practices guide for building robust, modern JVM/Android extensions.

Note: Bolt CLI is built upon the wonderful foundation of the Rush CLI project by Shreyash Saitwal. Sincere thanks to the original creators and developers for their paving work in JVM/App Inventor builder pipelines.

📂 Table of Contents

  1. Getting Started & Scaffolding
  2. Project Directory Architecture
  3. Configuration Reference (bolt.yml)
  4. The Dependency Classpath Model
  5. AndroidManifest.xml Integration
  6. Bytecode Optimization & Size Shrinking
  7. Automated Project Migration & Safe Backups

1. Getting Started & Scaffolding

Scaffolding a New Project

To create a new extension project, navigate to your desired directory and execute:

bolt create MyAwesomeExtension

This starts an interactive scaffolding wizard that sets up:

  1. Package Identifier: Your reverse-domain structure (e.g. com.mycompany.myawesomeextension).
  2. Language Selection: Scaffolds starter templates in Java or Kotlin. (Note: Both languages can be used together in the same project directory!)
  3. IDE Integration: Automatically configures files for VS Code (generating .vscode/settings.json), IntelliJ IDEA/Android Studio (generating .idea/ configs), or both. This allows instant classpath autocompletion for resolved JVM libraries.

2. Project Directory Architecture

A standard Bolt CLI project is organized cleanly to keep your codebase modular and maintainable:

MyAwesomeExtension/
├── assets/             <-- Static assets (images, JSONs, icons)
├── deps/               <-- Local .jar or .aar dependencies
├── out/                <-- Generated .aix and documentation
│   ├── MyExtension.aix
│   └── extension.txt
├── src/                <-- Java & Kotlin source files
│   ├── com/company/    <-- Source files matching package
│   ├── AndroidManifest.xml  <-- Custom Android Manifest
│   └── proguard-rules.pro   <-- Custom ProGuard rules
├── bolt.yml            <-- Project configuration file
├── README.md           <-- Documentation readme
└── tree.txt            <-- Visual directory tree (auto-generated by `bolt tree`)

Key Folders

  • assets/: Put static media or files here. Make sure to declare them in the assets block of bolt.yml to bundle them.
  • deps/: Put local dependency archives here. You can drop JAR or AAR files directly, and satisfy compilation and runtime classpaths instantly.
  • out/: Holds compiled assets. After bolt build finishes successfully, the output .aix bundle and auto-generated block specs documentation extension.txt reside here.

3. Configuration Reference (bolt.yml)

The behavior of the compiler, optimizer, and packager is driven entirely by the bolt.yml file located at the root of the project. Below is the complete key reference:

# Developer credit displayed in metadata/docs
author: 'Your Name'

# Minimum Android SDK level supported by the extension (e.g. API 19 = Android 4.4)
min_sdk: 19

# Optional: compile Android SDK API level (defaults to 35)
# compile_sdk: 35

# Enable Java 8 desugaring (allows using lambda expressions, streams, etc.)
desugar: true

# Enable R8 optimization pipeline
R8: true

# Enable ProGuard shrinking and optimization (defaults to false)
proguard: false

# Specify a custom ProGuard version to download and execute
proguard_version: '7.8.2'

# Strip heavyweight App Inventor metadata annotations post-compilation to save space
deannonate: true

# Automatically increment components' version counts inside source code on each build
auto_version: true

# External dependencies (remote Maven coordinates or local jars/aars in deps/)
dependencies:
  - example.jar
  - com.google.code.gson:gson:2.10.1

# Compile-time dependencies (not bundled into the output AIX file)
provided_dependencies:
  - com.google.android.material:material:1.9.0

# Assets list to bundle inside the extension
assets:
  - data.json

# Custom Maven repositories (JitPack, Central, and Google are pre-configured)
repositories:
  - https://jitpack.io

4. The Dependency Classpath Model

Selecting the correct classpath scope is essential to prevent duplicate class runtime crashes inside App Inventor APK compilations.

Scope A: Normal Dependencies (dependencies)

  • Usage: Third-party libraries that do not pre-exist on the user's host App Inventor companion or compile-time environments.
  • Result: Compiled and packed directly inside the extension's AndroidRuntime.jar inside the .aix bundle.
  • Warning: Do not bundle heavy Android support libraries, play services, or Kotlin stdlibs inside this block unless absolutely necessary, to avoid Duplicate Class Compilation Crashes during final APK packaging.

Scope B: Provided Dependencies (provided_dependencies)

  • Usage: Core libraries that already exist at runtime inside the App Inventor companion/runtime environment (such as Kotlin stdlib, App Inventor components runtime, or Android support library classes).
  • Result: Available to Java/Kotlin compilers (javac/kotlinc) for a successful compile, but excluded from the final .aix file.
  • Benefits: Guarantees ultra-tiny .aix file sizes and complete compatibility with the host runtime.

5. AndroidManifest.xml Integration

Bolt CLI fully integrates Android Manifest merging. Place your custom manifest at src/AndroidManifest.xml to declare services, providers, permissions, or receivers.

Shorthand Package Name Expansion

Writing long package paths inside the manifest is tedious. Bolt CLI introduces short-hand dot prefixes:

  1. Single Dot Prefix (.MyClass): Expands automatically to <package_name>.MyClass.

    <!-- Expands to: com.mycompany.myawesomeextension.MyService -->
<service android:name=".MyService" />

  2. Triple Dot Prefix (...MyAlias): Also expands to the fully qualified class name package.

    <activity-alias android:name="...MyActivityAlias" android:targetActivity=".MyActivity" />

Manifest merger conflicts

If a third-party dependency AAR brings its own manifest rules that conflict with your setup, you can safely use standard Android Tools attributes to resolve conflicts during compilation:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:tools="http://schemas.android.com/tools">
    <application>
        <service android:name=".MyService" tools:replace="android:exported" />
    </application>
</manifest>

6. Bytecode Optimization & Size Shrinking

Bytecode footprint size is a key metric in extension development. Bolt CLI provides three highly powerful optimization pipelines:

1. Bytecode Shrinking (R8 & ProGuard)

By setting R8: true or proguard: true in your bolt.yml, the compilation pipeline runs structural code shrinking:

  • Discards all unused Java/Kotlin standard library classes and methods.

  • Shrinks class scopes.

  • Customize keeping patterns inside src/proguard-rules.pro:

    # Preserve specific classes from being optimized or stripped
-keep class com.mycompany.myawesomeextension.SpecialHelper { *; }
-dontwarn com.mycompany.myawesomeextension.**

2. Metadata Annotation Stripping (deannonate)

App Inventor annotations (@SimpleEvent, @SimpleFunction, etc.) are converted to heavyweight runtime metadata.

  • Setting deannonate: true automatically strips these annotations post-compile.
  • Reduces .aix binary size significantly while fully preserving standard blocks loading.

3. Kotlin stdlib size optimization

Kotlin stdlib adds approximately 1.5MB to your .aix file. To shrink this:

  • Method A: Use provided_dependencies if standard Kotlin stdlibs are present on your target companion player.
  • Method B: Configure ProGuard to discard unused Kotlin helper files inside proguard-rules.pro.

7. Automated Project Migration & Safe Backups

Upgrading legacy extensions to modern Bolt CLI structures is fully automated and safe.

Automated pre-migration backups

Whenever the bolt migrate command is executed, Bolt CLI performs an automated backup:

  1. It zips the entire current project directory.
  2. Saves it as <projectName>_backup_<timestamp>.zip directly in the project root folder.
  3. Automatically ignores heavy directories like .git, .bolt, .dart_tool, and .rush to keep the backup ZIP clean and small.

Supported migration subcommands

  • bolt migrate rush: Upgrades a legacy Rush project, converting rush.yml to bolt.yml automatically.
  • bolt migrate fast: Upgrades a legacy Fast CLI project, converting fast.yml to bolt.yml.
  • bolt migrate template: Converts a traditional App Inventor extension-template directory setup into a clean Bolt project, restructuring the src/ layout.
  • bolt migrate ai2: Converts raw App Inventor components sources into a modular Bolt CLI extension project.

Clone this wiki locally