Capacitor Build CLI

This CLI tool automates the process of setting up the necessary environment and building Capacitor.js applications, specifically targeting Android. It handles the installation and configuration of Java Development Kits (JDKs), Android SDK command-line tools, and required Android SDK components, followed by executing the Gradle build process.

Support for Windows and Linux (some distributions) has been tested.

Installing CapacitorJs

Installation

To use this CLI, ensure you have Node.js installed. Then, you can run it directly from your project directory.

npm install @ea-utilities/build-capacitor -D

Usage

This CLI provides the following commands:

Commands

build command

Builds a Capacitor project.

Syntax

npx build-capacitor build [options]

Options

• --output-file, -o

  • Description: Specifies the output path and filename for the generated APK.
  • Type: string
  • Default: dist/app (e.g., dist/app.apk)
  • Example: npx build-capacitor build -o C:/apks/myapp-debug.apk

• --build-type, -t

  • Description: Defines the type of build to perform.
  • Type: string
  • Default: debug
  • Possible Values: debug, release (or other Gradle build types configured in your project)
  • Example: npx build-capacitor build -t debug

• --format, -f

  • Description: Specifies the format(s) to build.
  • Type: string
  • Default: apk
  • Possible Values: apk, aab (comma-separated for multiple)
  • Example: npx build-capacitor build -f apk,aab

Examples

• Build a debug APK (default output: dist/app.apk):

  npx build-capacitor build

• Build a debug APK and specify an output file:

  npx build-capacitor build -t debug -o C:/apks/myapp-debug.apk

clean command

Removes all downloaded applications and related files.

Syntax

npx build-capacitor clean

clean-cache command

Cleans only the Gradle cache.

Syntax

npx build-capacitor clean-cache

Build Command Details

The build command orchestrates the following steps:

1. Environment Setup:

   • Java Development Kit (JDK) Configuration: Downloads and configures JDK 17 and JDK 21. The build process will first attempt to use JDK 17, and if that fails, it will fall back to JDK 21.
   • Android Command-Line Tools: Downloads and sets up the necessary Android command-line tools (e.g., sdkmanager).
   • Android SDK Component Installation: Installs required Android SDK build tools (version 34.0.0) and platform API (API level 34). It also handles the acceptance of Android SDK licenses.

2. Gradle Build:

   • Executes the gradle assemble command to compile the Capacitor Android project. The build type (debug or release) is passed to Gradle.

3. APK Relocation:

   • Moves the generated APK file from the Gradle build output directory to the specified --output-file location.

Full Workflow Example (Angular with Capacitor)

This section provides a step-by-step guide for setting up and building an Angular Capacitor application using this CLI.

1. Create a new Angular project:

   npm i -g @angular/cli@latest
   ng new myapp
   cd myapp

2. Install Capacitor:

   npm install -g @capacitor/cli
   npm i @capacitor/android

3. Install this build CLI:

   npm install @ea-utilities/build-capacitor -D

4. Initialize Capacitor and add Android platform:

   npx cap init "myapp" "com.example.myapp" --web-dir "dist/myapp/browser"
   npx cap add android

5. Build and Sync (for new changes): Whenever you make changes to your Angular application, build it and sync with Capacitor before building the Android APK.

   ng build
   npx cap sync
   npx build-capacitor build

   The first build might take some time as it downloads and configures dependencies. Subsequent builds will be faster.

   The default output APK will be located at dist/app.apk.