Mobile App Builder

A cross-platform CLI builder and signer for Expo (Managed & Bare), Native React Native, and Android mobile projects. It automates bootstrapping dependencies, building, signing with keystores, and publishing applications.

Table of Contents

• Introduction
• Features
• Prerequisites
• Installation
• Usage
• Command Options
• Standalone Artifact Signing
• Build Profiles
• Workflow Steps
• Development
• License

Introduction

mobile-app-builder is an all-in-one CLI tool designed to streamline mobile builds for both Expo and Native (Bare) React Native projects. Instead of wrestling with complex cloud build configurations or manual Gradle signing setups, this tool automatically detects your project type, manages Android configurations safely, compiles APKs or AABs via Gradle, signs them with production or custom keystores, and optionally publishes to GitHub Releases or Google Play Store.

Features

• Dual Project Support: Works seamlessly on Expo projects (Managed CNG and Bare) as well as Native (Bare) React Native projects.
• Permanent Android Folder Safety: Automatically detects Native/Bare projects and never deletes or wipes your source-controlled android/ folder.
• Automated Native Generation: Automatically runs native prebuild only for Managed Expo projects where the android/ directory is ephemeral.
• Universal Signing Pipeline: Strips prior signatures and signs .apk and .aab artifacts using apksigner and jarsigner. Generates release keystores interactively and saves configurations to .env.local.
• Dynamic Configuration & Versioning: Automatically syncs version codes and version names directly into package.json, app.json, and android/app/build.gradle.
• Multiple Build Profiles: Supports dev (Debug APK), preview (Release APK), and prod (Release AAB).
• Environment Management: Inject specific .env files for different build flavors.
• Publishing & CI Integration: Generates GitHub Actions workflows (for production AABs), creates GitHub Releases, and triggers Play Store rollouts.

Prerequisites

Ensure you have the following installed on your machine (the doctor command can verify or install missing dependencies for you):

• Node.js (>= 22.0.0)
• Java Development Kit (JDK 21)
• Android SDK (Command Line Tools, Platform Tools, Build Tools)
• Git
• GitHub CLI (gh) (Required if using GitHub Release / Publish flags)

Installation

You can install mobile-app-builder directly from npm, or use it locally.

# Global installation
npm install -g mobile-app-builder

# Local installation in a React Native or Expo project
npm install --save-dev mobile-app-builder

Usage

Navigate to your React Native or Expo project directory and run the command using mobile-builder (or mobile-app-builder):

# Check environment and dependencies
npx mobile-builder doctor

# Build Android app
npx mobile-builder android [options]

Examples

Build a development APK:

npx mobile-builder android --dev

Build a release preview APK:

npx mobile-builder android --preview

Build a production AAB and publish:

npx mobile-builder android --prod --publish --track production --notes "Production release"

Test the build pipeline without running Gradle:

npx mobile-builder android --preview --dry-run

Standalone Artifact Signing

Already built an APK or AAB? You can sign or re-sign it directly with:

# Signs the latest AAB or APK found in ./build or current directory
npx mobile-builder sign

# Sign a specific artifact with a specified keystore
npx mobile-builder sign ./build/my-app.aab --keystore ./release.jks --alias my-key

Command Options

| Option | Description | | ----------------- | ------------------------------------------------------------------------- | | --dev | Build a Development APK (assembleDebug, preserves cache) | | --preview | Build a Preview APK (assembleRelease) | | --prod | Build a Production AAB (bundleRelease) | | --clean | Forces clean regeneration (Managed Expo only) | | --bump | Explicitly bump patch version in package.json | | --no-bump | Skip bumping patch version in package.json | | --publish | Publish to Google Play Store (via GitHub Actions workflow for --prod) | | --track <track> | Google Play Store track (e.g., production, beta, alpha, internal) | | --notes <notes> | Release notes for GitHub Release | | --dry-run | Run the full script but skip Gradle build, signing, and publishing | | --env <file> | Path to a specific environment file to load (e.g., .env.production) | | --cleanup | Force cleanup of ephemeral android/ directory (Managed Expo only) | | --no-cleanup | Keep the generated android/ folder after build |

Build Profiles

The builder automatically maps profiles to the correct build types and artifact formats:

1. Dev (--dev)

   • Profile Name: development
   • Build Task: assembleDebug
   • Output: app-debug.apk
   • Versioning: Preserves current version string and local versionCode
   • GitHub Release: Marked as Pre-release
   • Speed: Preserves android/ folder and Gradle daemon for fast incremental rebuilds

2. Preview (--preview)

   • Profile Name: preview
   • Build Task: assembleRelease
   • Output: app-release.apk
   • Signing: Automatically signed with release keystore
   • GitHub Release: Marked as Pre-release

3. Prod (--prod)

   • Profile Name: production
   • Build Task: bundleRelease
   • Output: app-release.aab
   • Versioning: Bumps patch version and increments versionCode
   • Signing: Strips prior signatures and signs AAB via jarsigner
   • GitHub Release: Marked as official Latest Release
   • CI/CD: Generates .github/workflows/publish.yml and triggers Play Store rollout if --publish is specified

Workflow Steps

When you run a build, the CLI automatically performs the following steps:

1. Project Detection: Detects whether the project is Expo (Managed or Bare) or Native React Native.
2. Bootstrapping: Validates system dependencies (Node, Java 21, Android SDK, Git, gh).
3. Version Management: Bumps package.json (for prod or if --bump is set) and syncs versionCode into Gradle or EAS.
4. Native Generation (Expo Managed only): Generates Android project files (expo prebuild). Skipped for Native React Native and Bare projects.
5. Gradle Patching: Injects memory optimizations, caching, daemon, and incremental settings into gradle.properties.
6. Gradle Build: Runs the Gradle wrapper with --build-cache, --parallel, and --configure-on-demand.
7. Signing: Strips any previous signatures and signs the artifact with keystore credentials (apksigner for APK, jarsigner for AAB).
8. Copying: Moves the finished .apk or .aab to the build/ directory in the root.
9. GitHub Release: Automatically creates/updates a GitHub Release (tagged as Pre-release for dev/preview). Skips gracefully if remote is unconfigured.
10. Play Store Rollout (Optional): If --publish is passed with --prod, triggers the Google Play Store deployment workflow.
11. Cleanup: Cleans up ephemeral android/ only on Managed Expo builds, while strictly preserving permanent native source code.

Development

# Clone the repository
git clone https://github.com/georgechitechi/mobile-app-builder.git
cd mobile-app-builder

# Install dependencies
npm install

# Watch mode for TypeScript
npm run dev

# Build the final dist
npm run build

License

MIT License. See LICENSE for more details.