BMT Mobile Build Tools

0.0.95 · active · verified Wed Apr 22

The `bmt-mobile-build-tools` package, currently at version 0.0.95, provides a collection of internal command-line utilities specifically designed to automate and streamline various aspects of mobile application build processes for both Android and iOS platforms. Its core functionalities include the automated uploading of compiled application binaries (APKs for Android, IPAs for iOS) to App Center, leveraging a configurable JSON structure for project details and distribution settings. Additionally, it offers robust capabilities for generating application icons and splash screens, which includes support for dynamically overlaying dates and version numbers onto the assets. This icon generation feature integrates with Ionic Pro for its underlying image processing requirements. As an internal build tool, its development and release cadence are typically aligned with the maintaining organization's internal product cycles, distinguishing it from general-purpose public libraries through its tailored integration with specific internal build environments and App Center workflows.

Common errors

```
Ionic Pro authentication required. Please enter your email and password.
```
cause The `bmt-mobile-build-tools icons` command was executed without the necessary Ionic Pro `$IONIC_EMAIL` and `$IONIC_PASSWORD` environment variables set, or invalid credentials were provided.

fix Set the `$IONIC_EMAIL` and `$IONIC_PASSWORD` environment variables in your shell, or run the command interactively to provide credentials when prompted.
```
Error: Configuration file not found at 'my/custom/config.json'.
```
cause The `--config` argument for the `upload` command specified a path that does not point to an existing App Center configuration file.

fix Correct the file path provided to the `--config` argument, ensuring the file exists at the specified location relative to the execution directory or as an absolute path.
```
Error: Missing required argument: --platform
```
cause The `bmt-mobile-build-tools upload` command was invoked without specifying the required `--platform` argument.

fix Include the `--platform` argument with a valid value (either `--platform=android` or `--platform=ios`) when running the `upload` command.
```
Error: Appcenter API response 401 Unauthorized.
```
cause The App Center API token provided in the `appcenter.config.json` file or via environment variables is either invalid, expired, or does not have sufficient permissions for the requested operation.

fix Verify that the `apiToken` in your `appcenter.config.json` or environment variables is correct, active, and belongs to an account with the necessary access rights in App Center.

Warnings

gotcha Icon and splash screen generation functionality (`bmt-mobile-build-tools icons`) requires an active Ionic Pro setup, including `$IONIC_EMAIL` and `$IONIC_PASSWORD` environment variables or interactive input. Without these, icon generation will fail.
Fix: Ensure Ionic Pro is correctly configured and authentication details are available in the environment before running the `icons` command.
gotcha Storing App Center API tokens directly in `appcenter.config.json` is a significant security risk, especially in version-controlled repositories. These tokens grant full access to your App Center projects.
Fix: Externalize sensitive credentials like `apiToken` using environment variables (e.g., `process.env.APPCENTER_API_TOKEN`) or a secure secrets management system, passing them dynamically if the tool supports environment variable substitution in config files.
gotcha The `--version=$npm_package_version` syntax for icon overlays is specifically designed for `package.json` scripts. `$npm_package_version` is an npm-provided environment variable that expands automatically within an npm script's context.
Fix: When running the `icons` command directly from the terminal outside of an `npm run` script, provide a fixed version number (e.g., `--version=1.0.0`) or omit the `--version` flag if not needed.
gotcha The `--config` argument for the `upload` command expects a valid path to your `appcenter.config.json` file. Incorrect or inaccessible paths will lead to file not found errors.
Fix: Verify that the path provided to `--config` is accurate and the file is accessible from the directory where the `bmt-mobile-build-tools` command is executed.

Install

npm install bmt-mobile-build-tools npm
yarn add bmt-mobile-build-tools yarn
pnpm add bmt-mobile-build-tools pnpm

Quickstart

Demonstrates how to configure and invoke the `bmt-mobile-build-tools` CLI for uploading builds to App Center and generating mobile application icons, including environment setup notes.

// This package is a Command Line Interface (CLI) tool. You interact with it directly from your terminal.
// Ensure `bmt-mobile-build-tools` is installed globally or available in your PATH.

// --- App Center Upload Configuration (appcenter.config.json example) ---
// Create a file named 'appcenter.config.json' in your project root or a specified path.
// Replace placeholder values with your actual App Center details and paths.
/*
{
    "dev": {
        "android": {
            "projectOwner": "your-appcenter-owner",
            "projectName": "your-android-app-name",
            "apiToken": "YOUR_APPCENTER_API_TOKEN", // Consider using environment variables for security
            "apkPath": "./platforms/android/app/build/outputs/apk/release/app-release.apk", // Adjust path
            "distributionSettings": {
                "destinations": [
                    {
                        "name": "Dev Testers Group"
                    }
                ],
                "release_notes": "Development build for testing."
            }
        },
        "ios": {
            "projectOwner": "your-appcenter-owner",
            "projectName": "your-ios-app-name",
            "apiToken": "YOUR_APPCENTER_API_TOKEN",
            "apkPath": "./platforms/ios/build/Release-iphoneos/your-app.ipa", // Adjust path
            "distributionSettings": {
                "destinations": [
                    {
                        "name": "iOS Dev Group"
                    }
                ],
                "release_notes": "iOS Development build."
            }
        }
    }
}
*/

// --- CLI Usage Examples ---

// 1. Upload an Android build to App Center using the 'dev' environment configuration.
// Make sure 'appcenter.config.json' is correctly set up.
// Run this command in your terminal:
// bmt-mobile-build-tools upload --platform=android --env=dev --config=appcenter.config.json

// 2. Generate application icons and splash screens.
// This command requires Ionic Pro credentials (IONIC_EMAIL, IONIC_PASSWORD) to be set as environment variables.
// Generate icons with the current date overlay:
// bmt-mobile-build-tools icons --date

// 3. Generate icons with a fixed version number overlay:
// bmt-mobile-build-tools icons --version=1.0.0

// 4. Generate icons with both current date and dynamic version from package.json (run as npm script):
// (Add to your package.json scripts section, e.g.: "build:icons": "bmt-mobile-build-tools icons --date --version=$npm_package_version")
// Then run from terminal: npm run build:icons

console.log("bmt-mobile-build-tools commands are executed directly in the terminal.");
console.log("Refer to the comments for example command structures and setup guidance.");

view raw JSON →