Installation
Choose Your Project Type
Bundle Drop supports Expo SDK 54–57 and bare React Native 0.71+ on iOS and Android. The CLI detects the project type and applies the matching setup while preserving your existing configuration.
If you use Expo, read the dedicated Expo guide for managed/CNG builds, Release behavior, runtime authority, and strict fingerprint checks.
Compatibility
| Surface | Supported versions |
|---|---|
| Expo | SDK 54–57 |
| Bare React Native | 0.71+ |
| Platforms | iOS and Android |
| Architecture | Old and New Architecture |
| Node.js | 20.19.4+ |
Install the Package
For Expo projects, let Expo select a compatible package version:
npx expo install @gfean/react-native-bundle-dropFor bare React Native projects, install with npm or Yarn, then update iOS pods:
npm install @gfean/react-native-bundle-drop
cd ios && pod install && cd ..Authenticate and Complete Setup
Before setup, create an organization and project in Bundle Drop. If you have not done that yet, start with Project Creation.
Run the interactive login from your app directory:
npx bundle-drop loginlogin authenticates the CLI, creates bundle.drop.config.js, detects Expo or bare React Native, previews the complete setup plan, and asks before applying changes. It also creates backups for files it changes.
After setup, verify the project:
npx bundle-drop doctorUse init when you want to rerun setup or need a non-interactive token flow:
npx bundle-drop init
npx bundle-drop init --project-type expo
npx bundle-drop init --project-type bare
npx bundle-drop init --token bdp_pat_xxxThe normal setup is intentionally unified. Expo projects receive the config plugin and Expo-preserving Metro wrapper. Bare projects receive the Metro config alias and the appropriate Release bundle resolver for their existing Android and iOS entrypoint shapes. There are no separate Metro or native initialization commands.
If guided setup stops because your project has a customized or ambiguous native entrypoint, use Manual Setup. It covers the current Kotlin ReactHost shape without recreating ReactNativeHost, existing legacy Kotlin and Java hosts, Swift and Objective-C app delegates, and Expo configuration.
Project Config
The CLI creates bundle.drop.config.js. The default runtime model is shared by Expo and bare React Native:
module.exports = {
projectType: "bare",
serverUrl: "https://api.bundledrop.app",
defaultChannel: "develop",
runtimeVersion: {
ios: "1.0.0",
android: "1.0.0",
},
org: { slug: "your-org-slug" },
project: {
name: "Your App Name",
slug: "your-app-slug",
apiKey: "your-project-api-key",
},
};Keep a platform runtime value unchanged for JavaScript and asset updates that remain compatible with the installed binary. Bump that platform's runtime and rebuild when native compatibility changes. See Runtime Version for the complete rule.
Existing bare projects without projectType remain supported. New configs include it so project detection stays explicit.
Bare React Native Integration
The setup plan preserves the native host style already used by your app:
- Modern Kotlin
ReactHostapps keep the directReactHostshape and receive a Release-only Bundle Drop bundle path. - Existing Kotlin or Java
ReactNativeHostapps receive the matchinggetJSBundleFile()integration. - Swift, Objective-C, and Objective-C++ app delegates receive the matching Release bundle resolver.
- Debug builds continue to use Metro.
If your native entrypoints are highly customized and the CLI cannot produce a safe plan, it stops without guessing. Follow Manual Setup, preserve the existing host and fallback behavior, and run npx bundle-drop doctor again.
Initialize Bundle Drop in JavaScript
Call BundleDrop.init once, early in application startup. For a conventional React Native entrypoint, initialize before registering the root component:
import { AppRegistry } from "react-native";
import { BundleDrop } from "@gfean/react-native-bundle-drop";
import App from "./App";
import { name as appName } from "./app.json";
BundleDrop.init({
enabled: !__DEV__,
environment: __DEV__ ? "development" : "production",
channelName: "develop",
policy: "on-next-launch",
});
AppRegistry.registerComponent(appName, () => App);Expo Router apps should initialize in app/_layout.tsx; see Expo.
Build the Native App
Setup changes native integration, so create and install a new native binary before testing OTA behavior. Bare projects use their normal Release build process. Expo managed/CNG projects apply the plugin through prebuild, expo run:*, or EAS Build.
Expo Go and Debug/development-client builds keep Bundle Drop OTA disabled so Metro remains the development source. Test cold-start OTA behavior with a non-Debug/Release build.
Related Docs
- For Expo setup and strict fingerprint policy, see Expo.
- For a guided-setup fallback, see Manual Setup.
- For startup policies and initialization, see BundleDrop.init.
- For compatibility boundaries, see Runtime Version.
- For publishing your first update, see Uploading.