react-native-fastbuild

A developer tool that makes React Native Android builds 5x to 10x faster, reduces cold/first-time builds from 40 minutes to 3–5 minutes, catches configuration and native errors in under 1 second, auto-recovers from architecture mismatches, and manages your Metro Bundler lifecycle automatically in its own dedicated terminal window.

  ____ _____ ____ _____   ____  _   _ ___ _     ____  
 |  _ \_   _| __ )__  /  | __ )| | | |_ _| |   |  _ \ 
 | |_) || | |  _ \ / /   |  _ \| | | || || |   | | | |
 |  _ < | | | |_) / /_   | |_) | |_| || || |___| |_| |
 |_| \_\|_| |____/____|  |____/ \___/|___|_____|____/ 
   React Native Android Acceleration & Fail-Fast Engine (v1.0.3)

⚡ Why standard react-native run-android is slow

1. 4x Redundant Native Compilations: React Native debug builds compile C++ engines (Hermes, TurboModules, Reanimated, Screens, Skia) for 4 separate CPU architectures (arm64-v8a, armeabi-v7a, x86, x86_64) even if you are only running on a single phone.
2. Third-Party C++ Submodules Compiling Redundant ABIs: Even with root properties set, submodules in node_modules compile C++ for all 4 architectures on cold builds.
3. Serialized Compilation & Clang Linker Overhead: Native CMake/Ninja compilation defaults to low thread counts and heavy debug symbol generation.
4. No C++ Compiler Cache (ccache): Every rebuild recompiles native files from scratch instead of reusing cached objects.
5. Late-Stage Build Failures: Missing C++ headers, syntax bugs, or missing Android SDK paths usually fail 20–30 minutes into the build during the CMake linker step.
6. Low Gradle RAM Allocation: Gradle defaults to 2048MB heap, causing severe Garbage Collection (GC) thrashing and frozen builds.
7. Metro Port Conflicts & Window Chaos: Metro bundler either fails to start, conflicts with port 8081, or spawns duplicate blank terminal windows.

🚀 How react-native-fastbuild solves this

• 🎯 Universal Subproject ABI Slicing: Dynamically forces ndk.abiFilters across all subprojects (Reanimated, Screens, Skia, GestureHandler), cutting 75% of C++ compilation work.
• ⚡ Multi-Core Ninja & LLD Fast Linker: Injects maximum Ninja thread parallelism (-j<all_cores>), LLVM fast linker (-fuse-ld=lld), and lightweight debug symbols (-gline-tables-only).
• 🧵 Multi-Threaded Kotlin IR Backend: Injects -Xbackend-threads=<cores> to compile Kotlin modules in parallel across all CPU cores.
• 🩹 Self-Healing ABI Auto-Recovery: If an APK built for an x86_64 emulator is deployed to an ARM phone, FastBuild automatically diagnoses the mismatch, cleans, and triggers an automated rebuild targeted strictly to your phone's architecture.
• 🔧 Automated Doctor Auto-Fixer (--fix): Automatically creates local.properties, tunes gradle.properties, fixes gradlew permissions, and configures ADB reverse proxy.
• 🖥️ Smart Metro Terminal Window: Opens Metro in a single dedicated terminal window named Metro (<Project>:<Port>) without duplicating blank windows.
• 📊 Compiler & Build Cache Analytics (cache:stats / cache:clean): Real-time inspection of ccache/sccache hit rates and one-command disk space reclaiming.
• 📱 Filtered React Native Logcat & Crash Monitor (logs): Streams color-coded JS console logs, Hermes exceptions, and RedBoxes while filtering out OS noise, and auto-detects startup crashes.
• ⏱️ Live 3-Line Progress Tracker: Real-time progress bar with live ticking elapsed clock (45s) / (1m 34s), major phase description, and individual task status.
• 🛡️ Sub-2s Pre-Flight Diagnostics (doctor): Validates JDK, Android SDK, NDK, CMake, JVM heap, and C++ header syntax before starting Gradle.

🏎️ Performance Benchmarks

| Build Type | Standard React Native CLI | FastBuild (android:fast) | Speed Improvement | | :--- | :--- | :--- | :--- | | Pre-Flight Diagnostics Scan | None (fails late) | < 800 ms | Instant Fail-Fast | | Metro Start & Port Forwarding | Manual / Blocking | ~1.5 seconds (Dedicated window) | Instant Setup | | Cold Build (1st time, no cache) | 30 – 45 minutes | ~3 – 5 minutes | ~8x – 10x Faster ⚡ | | Warm Incremental Build | 3 – 8 minutes | ~15 – 45 seconds | ~8x – 10x Faster ⚡ | | JS / TS Screen Update | Fast Refresh | < 1 second | Instant Hot Reload |

📦 Quick Start

Run instantly with npx (zero global installation required):

# 1. Run Pre-Flight Diagnostics & Auto-Repair (< 2s)
npx react-native-fastbuild doctor --fix

# 2. Build Fast, Launch Metro & Run on Device
npx react-native-fastbuild android:fast

🛠️ Project Installation

Install as a development dependency:

npm install --save-dev react-native-fastbuild
# or
yarn add --dev react-native-fastbuild

Add these scripts to your package.json:

{
  "scripts": {
    "android:fast": "rn-fastbuild run-android",
    "doctor": "rn-fastbuild doctor",
    "fix": "rn-fastbuild fix",
    "logs": "rn-fastbuild logs",
    "cache:stats": "rn-fastbuild cache:stats",
    "cache:clean": "rn-fastbuild cache:clean",
    "optimize": "rn-fastbuild optimize",
    "build:apk": "rn-fastbuild build-apk",
    "build:aab": "rn-fastbuild build-aab",
    "benchmark": "rn-fastbuild benchmark"
  }
}

💻 CLI Commands & Options

rn-fastbuild run-android (Alias: android:fast)

Executes the full accelerated build and run workflow:

1. Step 1: Pre-Flight Diagnostics & Device Target Selection
2. Step 2: Metro Bundler Health Check, Dedicated Window Launch & ADB Reverse Proxy
3. Step 3: Single-Slice ABI Compilation & Accelerated Gradle Build (with live 3-line timer)
4. Step 4: APK Installation, ABI Auto-Recovery & App Launch

rn-fastbuild run-android [options]

Options:

| Option | Description | Default | | :--- | :--- | :--- | | --port <number> | Custom Metro Bundler port | 8081 | | --abi <arch> | Target specific ABI (arm64-v8a, armeabi-v7a, x86_64, x86) | Connected device native ABI | | --universal | Compile all 4 ABIs without slicing | false | | --device <id> | Target specific ADB device/emulator ID | Auto-detect / Interactive prompt | | --variant <debug\|release> | Build variant | debug | | --clean | Run gradlew clean before build | false | | --no-packager | Skip launching Metro Bundler | false | | --dry-run | Simulate execution flow without modifying files | false |

rn-fastbuild doctor

Runs the instant pre-flight diagnostic scan across 11 vital health vectors:

rn-fastbuild doctor

# Auto-repair detected issues automatically:
rn-fastbuild doctor --fix

▶ Pre-Flight Diagnostic Matrix (< 2s scan)
  ✔  Java Development Kit (JDK)              : Found JDK (javac 17.0.18)
  ✔  Android SDK Path                        : Android SDK located at /Users/.../Library/Android/sdk
  ✔  Android NDK                             : Found NDK version 27.1.12297006
  ✔  CMake Build Engine                      : Found system CMake (cmake version 4.3.1)
  ✔  C++ Compiler Cache (ccache)             : Found ccache (v4.11.1). Active for native C++ builds.
  ✔  JVM Memory & Worker Allocation          : Configured for high-speed builds (Heap: 8192MB, Workers: 8)
  ✔  Target Android Device                   : Detected physical "Pixel 8" (ABI: arm64-v8a, API: 34)
  ✔  C++ Source & CMake Sanity               : Scanned native source files. No syntax or missing headers found.
  ✔  React Native Codegen / TurboModule Spec : Standard React Native New Architecture codegen active
  ✔  Metro Bundler Configuration             : Metro bundler config verified (metro.config.js)
  ✔  Project Path & File System              : Project path length is optimal (safe from MAX_PATH limits)

rn-fastbuild fix

Automatically creates missing configuration files (local.properties), sets up gradle.properties, fixes file permissions (chmod +x gradlew), and configures ADB reverse proxy.

rn-fastbuild fix

rn-fastbuild logs (Alias: logcat)

Streams filtered, color-coded React Native JavaScript logs, Hermes runtime exceptions, and native RedBoxes directly from your connected device:

rn-fastbuild logs

rn-fastbuild cache:stats & cache:clean

Inspect compiler cache hit rates and free up disk space:

# View ccache/sccache hit rate and Gradle cache size:
rn-fastbuild cache:stats

# Clean build outputs & caches to reclaim disk space:
rn-fastbuild cache:clean

rn-fastbuild build-apk & build-aab

Builds standalone APKs or Google Play Store bundles without launching a device:

# Debug APK with target device ABI slice (fastest)
rn-fastbuild build-apk

# Universal Debug APK (all 4 ABIs)
rn-fastbuild build-apk --universal

# Release APK
rn-fastbuild build-apk --release

# Google Play Store Bundle (.aab)
rn-fastbuild build-aab

❓ Frequently Asked Questions

📄 License

MIT © Yash Soni