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, orpacman. -
Smart Profile Updates: Safely configures
JAVA_HOMEandANDROID_HOMEin 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! ⚛️📱
