Tired of broken React Native environments? I built a CLI to fix that

Abdul Moueed — Sun, 16 Aug 2026 14:23:58 +0000

If you've worked with React Native long enough, you know the drill: everything worked fine yesterday, but today your project won't build because of a wrong JDK version, a stale ANDROID_HOME, missing SDK components, or CocoaPods fighting with macOS's system Ruby.

Setting up a React Native environment involves dozens of moving parts, and figuring out what's actually broken can waste hours.

So, I built rn-env-doctor — a zero-dependency CLI that checks your machine against React Native's official environment setup requirements and safely fixes what it can.

🛠️ What it checks

Instead of throwing vague errors, rn-env-doctor inspects your exact system setup across core tooling and platform targets:

Core Tooling: Node.js, nvm, Git, Watchman, Homebrew / winget / Chocolatey
Android: JDK 17, JAVA_HOME, ANDROID_HOME, adb, SDK Platform 35, and Build Tools 36.0.0
iOS (macOS): Xcode, Command Line Tools, Ruby, rbenv / RVM, and CocoaPods

Whenever a check fails, it explains what's wrong and provides an actionable fix.

✨ Key Features

Zero Dependencies: No npm packages are required. Clone the repository and run it directly.
Automatic Setup: With your explicit confirmation, it can install missing tools through Homebrew, winget, Chocolatey, apt, dnf, or pacman.
Smart Profile Updates: Safely configures JAVA_HOME and ANDROID_HOME in your shell profiles without creating duplicate entries.
Safe by Default: It always asks before making system changes.
Cross-Platform: Works out of the box on macOS, Linux, and Windows.

⚡ Quick Start

Option 1: If you already have Node installed

git clone https://github.com/Fs0ci3ty19/rn-env-doctor.git
cd rn-env-doctor

# Run interactive check & fix
node bin/rn-env-doctor.js

# Run a completely read-only audit
node bin/rn-env-doctor.js --check

# Automated setup (accept all fixes)
node bin/rn-env-doctor.js --yes

Option 2: Bootstrap scripts (if Node isn't installed yet)

macOS / Linux:

git clone https://github.com/Fs0ci3ty19/rn-env-doctor.git
cd rn-env-doctor
chmod +x bootstrap.sh
./bootstrap.sh

Windows (PowerShell):

git clone https://github.com/Fs0ci3ty19/rn-env-doctor.git
cd rn-env-doctor
.\bootstrap.ps1

🚧 What It Doesn't Do (By Design)

Some large GUI software and runtime-heavy components are intentionally left to their official installers:

Android Studio
Xcode
Android Virtual Devices (AVDs)
iOS Simulator runtimes

For these, rn-env-doctor tells you exactly what's missing and guides you on what needs to be configured manually.

🤝 Open Source & Feedback

The project is MIT licensed and completely open source:

🔗 GitHub Repository: https://github.com/Fs0ci3ty19/rn-env-doctor

Note: It's currently not published to npm, so for now, you'll need to clone the repository and run it directly.

If you give it a try, I'd love to hear what it catches on your machine; especially if you spot an edge case on your specific OS or Linux distribution. Issues and PRs are always welcome! ⚛️📱

DEV Community: Abdul Moueed