simplify bare React Native testing with Starship and QR codes

Bare React Native projects with custom native modules have always forced developers into a frustrating tangle of USB cables, IP shuffling, and fragile manual setup—just to see code changes on a real Android device. The new Starship CLI takes that Expo Go "scan a QR, you're live" simplicity and finally brings it to bare React Native apps, custom native code and all. The win? Real wireless debugging for native code projects, no Expo lock-in, no device plugging. Here’s why it matters, how it works, and how to use it—plus the honest comparison with Expo Go and classic RN CLI methods.

Why is debugging bare React Native apps with custom native modules so complicated?

Debugging a bare React Native app with custom native modules—anything beyond Expo Go’s vanilla workflow—has always required a stubborn amount of manual, repetitive tinkering. The traditional steps:

1. Plug device in via USB.
2. Run adb reverse tcp:8081 tcp:8081 to pipe Metro traffic.
3. Build APK (./gradlew assembleDebug).
4. Install APK on device—sometimes adb install, sometimes through Android Studio.
5. Open the app—usually met with “Unable to load script.”
6. Shake device, dig into the dev menu, manually type in your laptop’s IP and port for Metro.
7. Shake again, trigger reload.
8. If your IP or WiFi network changes? Repeat.

Count it: at least 5-7-step manual dance, with plenty of places to mistype, forget, or unplug. Expo Go simplified steps 4–7 into “scan, run”—but it chokes on custom modules. The result is a classic frustration loop: five-plus steps, every time, plus “IP changed” mayhem. A tiny typo or not-yet-arrived adb connection means another roundtrip.

Expo Go is a shortcut, but only if you don’t need custom native code. As soon as you want a bespoke module or library with native Android code, you’re back to the bare-metal grind. For many teams, that’s every day.

Takeaway: classic bare React Native debugging is friction-heavy and error-prone by design—a cable-bound, setup-heavy process unsuited to modern dev loops.

What is React Native Starship and how does it improve debugging?

React Native Starship is a new CLI tool (see the Medium launch article) that takes Expo Go’s hallmark QR-code-driven, instant onboarding and brings it to bare React Native projects—including ones with custom native modules. The core innovation: Starship bakes your local IP address directly into the debug APK, exposes a QR code in your dev terminal, and manages the install and Metro handshake—no USB, adb, or manual IP config required.

How it simplifies:

• Single command: npx react-native starship handles build, APK generation, local IP embedding, QR code presentation.
• Zero manual config: No explicit Metro setup, no IP address entry, no reverse port forwarding—it’s handled at build time by Starship’s tiny ContentProvider, writing your computer IP to SharedPreferences in the built APK.
• Wireless-first: Any device on the same WiFi as your dev box scans the QR, downloads and installs the APK, then connects instantly to Metro for fast refresh. No Expo account, no cable.

It replaces the cable-and-shake dance with—literally—a camera tap and 10 seconds of waiting. The loop matches Expo Go for frictionlessness, but for the cases that Expo Go can’t touch: custom native code. The CLI is straight to the point, the QR-coded APK is pre-configured, and subsequent sessions exploit build caching for even faster reloads.

Takeaway: Starship brings true Expo Go–style wireless debugging to the only place Expo can’t go—bare RN apps with custom modules, all with a single command and scan.

How to set up and use React Native Starship today?

Deploying Starship in a bare React Native project is 100% CLI-based and takes minutes. Here’s the workflow as documented in the Medium release and the github:

1. Install Starship

Add Starship to your (existing) bare React Native project:

yarn add react-native-starship

or

npm install react-native-starship

2. Start everything up

Make sure your Metro server is running, and then launch Starship from your project root:

npx react-native starship

This command:

• Builds a debug APK, injecting your current local IP into the APK at build time.
• Shows a QR code right in your terminal, representing the unique download URL for your APK.
• Tracks the build time and caches the APK for future incremental reloads.

3. Scan the QR from your Android device

With your device on the same LAN as your dev machine:

• Open your camera and point it at the displayed QR code.
• Accept the download/install prompt for the APK (you may need to allow unknown sources).

4. Let Starship handle the rest

• The device downloads and installs the custom APK.
• App launches automatically.
• Metro server autoconnects (via Starship’s injected IP config).
• Fast Refresh is immediately active; edits in JavaScript trigger reloads over the air.

Takeaway: Starship’s speed and multi-device support shave minutes off every dev/test cycle but are currently Android/debug only by design.

Can I use Starship for production or only debug builds?

Starship is strictly for development and debug workflows—not for production-signing or distribution. The build is configured for rapid iteration—debug flags, relaxed restrictions, and embedded local IP for fast Metro reloads.

Why only debug?

• APK is unsigned for release, contains debug IP config via ContentProvider, and expects a running Metro dev server.
• Designed for inner-loop developer iteration, not for store submission or production-grade testing.

For release: revert to your standard CLI/Gradle signing pipeline.

Takeaway: Starship accelerates local iteration; deploy with standard Gradle or CI for production releases.

The bottom line: QR-powered, Expo Go–simple debugging for custom/native React Native dev

React Native Starship finally closes the gap for teams building on bare React Native—making QR code–powered, zero-USB, instant wireless debugging real, even with custom native modules or multi-device test labs. Skip the traditional maze of cables, IP typing, and device juggling: npx react-native starship is now a standard part of the inner dev loop. If cable pain or Expo-native lockout are sapping your cycle times, give Starship a run—faster feedback for every save, on real hardware, no compromise. The native module bottleneck is gone.

Originally published at otf-kit.dev — full-stack kits your AI coding agent can actually ship to production. See the kits →