@gfean/react-native-bundle-drop 0.4.3 → 0.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/BundleDropExpo.podspec +21 -0
  2. package/README.md +250 -124
  3. package/android/src/main/java/com/bundledrop/BundleDropNativePaths.kt +33 -3
  4. package/app.plugin.js +3 -0
  5. package/expo/android/build.gradle +159 -0
  6. package/expo/android/src/main/AndroidManifest.xml +1 -0
  7. package/expo/android/src/main/java/com/bundledrop/expo/BundleDropExpoConfiguration.kt +35 -0
  8. package/expo/android/src/main/java/com/bundledrop/expo/BundleDropExpoIdentityModule.kt +30 -0
  9. package/expo/android/src/main/java/com/bundledrop/expo/BundleDropExpoPackage.kt +29 -0
  10. package/expo/android/src/main/java/com/bundledrop/expo/BundleDropExpoReactNativeHostHandler.kt +16 -0
  11. package/expo/bundle-drop-expo-gradle-plugin/build.gradle +31 -0
  12. package/expo/bundle-drop-expo-gradle-plugin/src/main/groovy/com/bundledrop/gradle/BundleDropExpoPlugin.groovy +83 -0
  13. package/expo/bundle-drop-expo-gradle-plugin/src/main/groovy/com/bundledrop/gradle/GenerateBundleDropBuildIdentityTask.groovy +57 -0
  14. package/expo/ios/Sources/BundleDropExpoIdentity.m +31 -0
  15. package/expo/ios/Sources/BundleDropExpoReactDelegateHandler.swift +24 -0
  16. package/expo-module.config.json +19 -0
  17. package/ios/BundleDropLocator.swift +7 -1
  18. package/lib/CLI/cli.d.ts +1 -2
  19. package/lib/CLI/cli.js +151 -56
  20. package/lib/CLI/logo.js +1 -1
  21. package/lib/CLI/scripts/aipowered/apply-setup-plan.d.ts +12 -0
  22. package/lib/CLI/scripts/aipowered/{apply-plan.js → apply-setup-plan.js} +24 -19
  23. package/lib/CLI/scripts/aipowered/backend-client.d.ts +4 -4
  24. package/lib/CLI/scripts/aipowered/backend-client.js +7 -7
  25. package/lib/CLI/scripts/aipowered/init-project-config.d.ts +17 -0
  26. package/lib/CLI/scripts/aipowered/init-project-config.js +418 -0
  27. package/lib/CLI/scripts/aipowered/scanner.d.ts +10 -3
  28. package/lib/CLI/scripts/aipowered/scanner.js +225 -201
  29. package/lib/CLI/scripts/aipowered/types.d.ts +37 -33
  30. package/lib/CLI/scripts/aipowered/validate-plan.d.ts +9 -2
  31. package/lib/CLI/scripts/aipowered/validate-plan.js +70 -119
  32. package/lib/CLI/scripts/bare-metro-config.d.ts +7 -0
  33. package/lib/CLI/scripts/{init-metro-config.js → bare-metro-config.js} +16 -30
  34. package/lib/CLI/scripts/doctor.d.ts +17 -0
  35. package/lib/CLI/scripts/doctor.js +410 -0
  36. package/lib/CLI/scripts/expo/build-receipt.d.ts +26 -0
  37. package/lib/CLI/scripts/expo/build-receipt.js +223 -0
  38. package/lib/CLI/scripts/expo/configure-expo.d.ts +28 -0
  39. package/lib/CLI/scripts/expo/configure-expo.js +268 -0
  40. package/lib/CLI/scripts/expo/eas-build-proof.d.ts +22 -0
  41. package/lib/CLI/scripts/expo/eas-build-proof.js +116 -0
  42. package/lib/CLI/scripts/expo/package-manager.d.ts +11 -0
  43. package/lib/CLI/scripts/expo/package-manager.js +84 -0
  44. package/lib/CLI/scripts/expo/write-build-receipt.d.ts +25 -0
  45. package/lib/CLI/scripts/expo/write-build-receipt.js +325 -0
  46. package/lib/CLI/scripts/expo/write-eas-build-receipt.d.ts +8 -0
  47. package/lib/CLI/scripts/expo/write-eas-build-receipt.js +71 -0
  48. package/lib/CLI/scripts/init-config.d.ts +18 -1
  49. package/lib/CLI/scripts/init-config.js +29 -8
  50. package/lib/CLI/scripts/login-cli.js +21 -3
  51. package/lib/CLI/scripts/native-setup-contract.d.ts +7 -0
  52. package/lib/CLI/scripts/native-setup-contract.js +101 -0
  53. package/lib/CLI/scripts/post-init.d.ts +6 -1
  54. package/lib/CLI/scripts/post-init.js +6 -33
  55. package/lib/CLI/scripts/upload-cli.d.ts +1 -0
  56. package/lib/CLI/scripts/upload-cli.js +106 -36
  57. package/lib/context.d.ts +0 -2
  58. package/lib/context.js +18 -2
  59. package/lib/expo/buildIdentity.d.ts +15 -0
  60. package/lib/expo/buildIdentity.js +201 -0
  61. package/lib/expo/buildReceipt.d.ts +42 -0
  62. package/lib/expo/buildReceipt.js +272 -0
  63. package/lib/expo/config.d.ts +7 -0
  64. package/lib/expo/config.js +43 -0
  65. package/lib/expo/configCache.d.ts +1 -0
  66. package/lib/expo/configCache.js +20 -0
  67. package/lib/expo/errors.d.ts +6 -0
  68. package/lib/expo/errors.js +11 -0
  69. package/lib/expo/expoUpdatesOwnership.d.ts +13 -0
  70. package/lib/expo/expoUpdatesOwnership.js +22 -0
  71. package/lib/expo/exportExpoProject.d.ts +21 -0
  72. package/lib/expo/exportExpoProject.js +125 -0
  73. package/lib/expo/exportValidation.d.ts +11 -0
  74. package/lib/expo/exportValidation.js +115 -0
  75. package/lib/expo/index.d.ts +18 -0
  76. package/lib/expo/index.js +25 -0
  77. package/lib/expo/localModules.d.ts +4 -0
  78. package/lib/expo/localModules.js +51 -0
  79. package/lib/expo/nativeIdentity.d.ts +1 -0
  80. package/lib/expo/nativeIdentity.js +17 -0
  81. package/lib/expo/projectType.d.ts +7 -0
  82. package/lib/expo/projectType.js +200 -0
  83. package/lib/expo/runtimeVersion.d.ts +13 -0
  84. package/lib/expo/runtimeVersion.js +45 -0
  85. package/lib/expo/types.d.ts +15 -0
  86. package/lib/expo/types.js +2 -0
  87. package/lib/fs/userProperties.d.ts +0 -2
  88. package/lib/fs/userProperties.js +0 -3
  89. package/lib/index.d.ts +1 -1
  90. package/lib/index.js +1 -2
  91. package/lib/loadConfig.d.ts +15 -7
  92. package/lib/loadConfig.js +2 -19
  93. package/lib/metro.d.ts +17 -0
  94. package/lib/metro.js +57 -0
  95. package/lib/native/bundleDropNative.d.ts +2 -0
  96. package/lib/native/bundleDropNative.js +9 -1
  97. package/lib/runtime/service.js +12 -1
  98. package/lib/scripts/bundle.d.ts +2 -2
  99. package/lib/scripts/bundle.js +10 -97
  100. package/lib/scripts/canonicalArtifact.d.ts +30 -0
  101. package/lib/scripts/canonicalArtifact.js +212 -0
  102. package/lib/scripts/exportProject.d.ts +41 -0
  103. package/lib/scripts/exportProject.js +82 -0
  104. package/package.json +51 -46
  105. package/plugin/constants.js +9 -0
  106. package/plugin/expoUpdates.js +131 -0
  107. package/plugin/index.js +11 -0
  108. package/plugin/markers.js +31 -0
  109. package/plugin/withBundleDrop.js +36 -0
  110. package/plugin/xcodeBuildPhase.js +77 -0
  111. package/react-native.config.js +15 -0
  112. package/lib/CLI/scripts/aipowered/apply-plan.d.ts +0 -10
  113. package/lib/CLI/scripts/aipowered/init-native-config.d.ts +0 -2
  114. package/lib/CLI/scripts/aipowered/init-native-config.js +0 -131
  115. package/lib/CLI/scripts/init-metro-config.d.ts +0 -2
@@ -0,0 +1,21 @@
1
+ require "json"
2
+
3
+ package = JSON.parse(File.read(File.join(__dir__, "package.json")))
4
+ native_version = package["nativeVersion"] || package["version"]
5
+
6
+ Pod::Spec.new do |s|
7
+ s.name = "BundleDropExpo"
8
+ s.version = native_version
9
+ s.summary = "Expo startup adapter for Bundle Drop"
10
+ s.homepage = package["homepage"]
11
+ s.license = package["license"]
12
+ s.authors = package["author"]
13
+ s.source = { :git => ".git", :tag => "#{s.version}" }
14
+
15
+ s.platforms = { :ios => "15.1" }
16
+ s.source_files = "expo/ios/Sources/**/*.{h,m,mm,swift}"
17
+ s.static_framework = true
18
+ s.swift_version = "5.9"
19
+ s.dependency "BundleDrop"
20
+ s.dependency "ExpoModulesCore"
21
+ end
package/README.md CHANGED
@@ -6,12 +6,11 @@
6
6
  [![docs](https://img.shields.io/badge/docs-bundledrop.app%2Fdocs-0f766e)](https://bundledrop.app/docs)
7
7
  [![dashboard](https://img.shields.io/badge/dashboard-developer.bundledrop.app-111827)](https://developer.bundledrop.app)
8
8
 
9
- **Ship OTA updates to React Native with confidence.**
9
+ **Ship reliable over-the-air updates to Expo and bare React Native apps.**
10
10
 
11
- Push instant over-the-air updates to your React Native apps and skip the App Store
12
- and Play Store review cycle entirely. Full-bundle reliability with patch-sized
13
- downloads — a drop-in [CodePush alternative](https://bundledrop.app/codepush-alternative)
14
- for bare React Native.
11
+ Bundle Drop delivers JavaScript and asset updates to compatible iOS and Android
12
+ binaries, with channel-based releases, targeted rollouts, rollback safety, and
13
+ patch-sized downloads.
15
14
 
16
15
  [Website](https://bundledrop.app) • [Docs](https://bundledrop.app/docs) • [Dashboard](https://developer.bundledrop.app) • [Coming from CodePush?](https://bundledrop.app/codepush-alternative)
17
16
 
@@ -19,91 +18,246 @@ for bare React Native.
19
18
 
20
19
  ## Why Bundle Drop?
21
20
 
22
- Shipping a small fix should not require a full mobile release.
21
+ Shipping a JavaScript or asset fix should not always require a new native build.
23
22
 
24
- | The old way | With Bundle Drop |
23
+ | Native release workflow | With Bundle Drop |
25
24
  | --- | --- |
26
- | Fix a typo, rebuild the whole app. | Publish the JavaScript change from your machine or CI. |
27
- | Wait days on an App Store / Play Store review. | Compatible devices pick it up in minutes, no review cycle. |
28
- | Users stay on the broken version until they manually update. | Roll it out gradually, and roll back instantly if something looks off. |
25
+ | Rebuild the app for every JavaScript or asset change. | Publish OTA-compatible changes from your machine or CI. |
26
+ | Wait for users to install the next store version. | Compatible devices can receive an update on their next check. |
27
+ | Leave a faulty release active until another binary ships. | Stop a rollout or return to a verified bundle quickly. |
29
28
 
30
- Over-the-air updates deliver the JavaScript and assets that run on top of your
31
- existing native binary — so the fixes and features that don't touch native code
32
- reach users the moment you publish them.
29
+ Bundle Drop only delivers updates that match the installed app's native and
30
+ runtime identity. Native changes still require a new App Store or Play Store build.
33
31
 
34
32
  ---
35
33
 
36
34
  ## Features
37
35
 
38
- - **Instant delivery** — publish an update and compatible devices pick it up on their next check.
36
+ - **Expo and bare React Native support** — use the Expo config plugin or native
37
+ React Native autolinking.
39
38
  - **Channel-based distribution** — ship to `develop`, `production`, `beta`, or any channel you define.
40
39
  - **Targeted rollouts** — stage releases and target specific cohorts with user properties.
41
- - **Rollback safety** — every install is a verified, immutable bundle; rollback is an instant local pointer switch.
42
- - **Hybrid OTA transport** — full-bundle reliability with patch-sized downloads (see [below](#hybrid-ota-delivery)).
43
- - **Version gating** — updates only reach binaries they're compatible with, so a JS update never lands on the wrong native build.
44
- - **Works with your error stack** — per-bundle hashes and source maps keep stack traces accurate in Sentry, Bugsnag, Datadog, or anything else.
45
- - **CI/CD friendly** — upload with a Personal Access Token from any pipeline.
40
+ - **Rollback safety** — every install is a verified, immutable bundle; rollback is a local pointer switch.
41
+ - **Hybrid OTA transport** — keep full-bundle integrity while supported devices download patch-sized changes.
42
+ - **Runtime gating** — updates only reach compatible native binaries.
43
+ - **Observability metadata** — bundle hashes and source maps keep crash reports attributable to the correct release.
44
+ - **CI/CD support** — upload with a Personal Access Token from any pipeline.
46
45
 
47
- Built for production React Native apps on iOS and Android.
46
+ ## Compatibility
48
47
 
49
- ---
48
+ | Surface | Supported versions |
49
+ | --- | --- |
50
+ | Expo | SDK 54, 55, 56, and 57 |
51
+ | Bare React Native | React Native 0.71 and newer |
52
+ | Platforms | iOS and Android |
53
+ | Architectures | Legacy architecture and New Architecture |
54
+ | Node.js | 20.19.4 or newer |
55
+ | React | 17 or newer |
50
56
 
51
57
  ## Installation
52
58
 
59
+ ### Expo
60
+
61
+ Install the package with Expo's version-aware installer:
62
+
63
+ ```bash
64
+ npx expo install @gfean/react-native-bundle-drop
65
+ ```
66
+
67
+ Bundle Drop's setup command registers the config plugin and preserves your existing
68
+ Expo Metro configuration.
69
+
70
+ ### Bare React Native
71
+
72
+ Install with your package manager:
73
+
53
74
  ```bash
54
75
  npm install @gfean/react-native-bundle-drop
55
- # or: yarn add @gfean/react-native-bundle-drop
76
+ # or
77
+ yarn add @gfean/react-native-bundle-drop
56
78
  ```
57
79
 
80
+ Then install the iOS pod:
81
+
58
82
  ```bash
59
83
  cd ios && pod install
60
84
  ```
61
85
 
62
- ---
86
+ React Native autolinking handles the package on both platforms. The setup command
87
+ adds the app-entry integration that allows a Release build to start an installed OTA.
63
88
 
64
- ## Quick Start
89
+ ## First-Time Setup
65
90
 
66
- ### 1. Connect your project
91
+ Run these commands from your app's project root:
67
92
 
68
93
  ```bash
69
94
  npx bundle-drop login
70
- npx bundle-drop init
95
+ npx bundle-drop doctor
71
96
  ```
72
97
 
73
- `init` generates `bundle.drop.config.js` from your logged-in account context.
74
- Optionally, apply the native wiring automatically:
98
+ `login` signs you in, creates `bundle.drop.config.js` when needed, detects Expo or
99
+ bare React Native, previews the integration changes, and completes setup. `doctor`
100
+ then validates configuration, runtime identity, native integration, and startup
101
+ ownership.
102
+
103
+ Run `init` when you need to review or rerun setup. You can force project detection
104
+ for unusual repository layouts:
75
105
 
76
106
  ```bash
77
- npx bundle-drop init-native # patches AppDelegate / MainApplication
78
- npx bundle-drop init-metro # lets Metro resolve bundle.drop.config.js
107
+ npx bundle-drop init
108
+ npx bundle-drop init --project-type expo
109
+ npx bundle-drop init --project-type bare
79
110
  ```
80
111
 
81
- ### 2. Bootstrap Bundle Drop in your app
112
+ Run `npx bundle-drop doctor` again after changing native integration, Metro, Expo
113
+ configuration, or runtime versions.
82
114
 
83
- Call `init` once, as early as possible in your app entrypoint:
115
+ ## Initialize the Runtime
84
116
 
85
- ```ts
117
+ Call `BundleDrop.init` once, as early as possible in the app process.
118
+
119
+ ### Expo Router
120
+
121
+ Initialize in `app/_layout.tsx`, before rendering the root layout:
122
+
123
+ ```tsx
124
+ import { BundleDrop } from '@gfean/react-native-bundle-drop';
125
+ import { Stack } from 'expo-router';
126
+
127
+ BundleDrop.init({
128
+ enabled: !__DEV__,
129
+ environment: __DEV__ ? 'development' : 'production',
130
+ channelName: 'develop',
131
+ policy: 'on-next-launch',
132
+ });
133
+
134
+ export default function RootLayout() {
135
+ return <Stack />;
136
+ }
137
+ ```
138
+
139
+ ### Conventional React Native entrypoint
140
+
141
+ Initialize near the top of your entry file, before registering the root component:
142
+
143
+ ```tsx
144
+ import { AppRegistry } from 'react-native';
86
145
  import { BundleDrop } from '@gfean/react-native-bundle-drop';
87
146
 
147
+ import App from './App';
148
+ import { name as appName } from './app.json';
149
+
88
150
  BundleDrop.init({
89
151
  enabled: !__DEV__,
90
152
  environment: __DEV__ ? 'development' : 'production',
91
- channelName: 'develop', // the channel created for every new project by default
153
+ channelName: 'develop',
92
154
  policy: 'on-next-launch',
93
155
  });
156
+
157
+ AppRegistry.registerComponent(appName, () => App);
94
158
  ```
95
159
 
96
- ### 3. Ship an update
160
+ ## Expo Builds and Development
161
+
162
+ Bundle Drop needs its native integration in the installed app. Expo Go does not
163
+ contain that native adapter, so the SDK remains disabled there and your app can keep
164
+ using Expo Go for normal development.
165
+
166
+ Debug builds and development clients also keep Metro as the JavaScript authority;
167
+ they do not start an installed OTA bundle. Test the OTA lifecycle with a non-Debug
168
+ Release build.
169
+
170
+ For managed/CNG projects, setup can leave `ios/` and `android/` absent. The config
171
+ plugin generates the native integration during a later prebuild, `expo run:*`, or
172
+ EAS Build. Typical local Release builds are:
173
+
174
+ ```bash
175
+ npx expo run:ios --configuration Release
176
+ npx expo run:android --variant release
177
+ ```
178
+
179
+ For remote builds, use your normal EAS profiles:
180
+
181
+ ```bash
182
+ eas build --platform ios
183
+ eas build --platform android
184
+ ```
185
+
186
+ With the default literal runtime configuration, the plugin embeds the platform's
187
+ literal in the native build and Expo uploads resolve that same literal directly from
188
+ `bundle.drop.config.js`. This normal workflow does not require a build receipt.
189
+
190
+ An advanced Expo project can explicitly make its Expo runtime policy authoritative
191
+ with `runtimeVersion: { source: 'expo' }`. In that opt-in mode, uploads require an
192
+ exact receipt from the matching local native build. For a remote EAS build, create an
193
+ authenticated receipt from the completed build and pass the returned path to upload:
194
+
195
+ ```bash
196
+ npx bundle-drop eas-receipt ios --build-id <eas-build-id>
197
+ npx bundle-drop upload ios --channel develop --build-receipt <receipt-path>
198
+ ```
199
+
200
+ Rebuild the native app whenever the config plugin, native dependencies, permissions,
201
+ or runtime compatibility boundary changes.
202
+
203
+ ### `expo-updates` startup ownership
204
+
205
+ An active `expo-updates` installation can also own native startup, so it cannot be
206
+ active in the same binary as Bundle Drop. Setup and `doctor` stop when they detect
207
+ that conflict. To migrate intentionally, review the proposed changes and run:
208
+
209
+ ```bash
210
+ npx bundle-drop init --project-type expo --migrate-expo-updates
211
+ ```
212
+
213
+ This removes the active `expo-updates` integration and requires a new native binary.
214
+ Do not publish a Bundle Drop update until that replacement binary has been built and
215
+ distributed.
216
+
217
+ ## Runtime Versions
218
+
219
+ `bundle.drop.config.js` defines literal runtime versions shared by Expo and bare
220
+ React Native projects:
221
+
222
+ ```js
223
+ module.exports = {
224
+ // ...project configuration
225
+ runtimeVersion: {
226
+ ios: '1.0.0',
227
+ android: '1.0.0',
228
+ },
229
+ };
230
+ ```
231
+
232
+ Keep a platform's literal unchanged for OTA-compatible JavaScript and asset updates.
233
+ The upload will then target binaries built with that same runtime value.
234
+
235
+ When native code or native configuration changes, bump the affected platform's
236
+ literal and build a new binary before uploading updates for that runtime. For
237
+ example, an iOS-only native change should bump `runtimeVersion.ios`; Android can keep
238
+ its existing value. This makes the compatibility boundary explicit and prevents an
239
+ update from reaching a binary that cannot run it.
240
+
241
+ ## Upload an Update
242
+
243
+ With the default literal runtime configuration, Expo uploads resolve the app version
244
+ through the Expo project and the runtime through `bundle.drop.config.js`. They do not
245
+ need `--version`, `--plist-file`, or Gradle-path options:
246
+
247
+ ```bash
248
+ npx bundle-drop upload ios --channel develop
249
+ npx bundle-drop upload android --channel develop
250
+ ```
251
+
252
+ Bare React Native uploads specify or resolve the app version explicitly:
97
253
 
98
254
  ```bash
99
255
  npx bundle-drop upload android --version 1.2.3 --channel develop
100
256
  npx bundle-drop upload ios --plist-file ios/Info.plist --channel develop
101
257
  ```
102
258
 
103
- Add `--sourcemap` to keep crash reports readable, and `--token <PAT>` to upload
104
- from CI/CD without an interactive login.
105
-
106
- ---
259
+ Add `--sourcemap` to produce source maps for error tracking. In CI/CD, pass a
260
+ Personal Access Token with `--token <PAT>` instead of using an interactive login.
107
261
 
108
262
  ## Update Policies
109
263
 
@@ -113,19 +267,18 @@ from CI/CD without an interactive login.
113
267
  | --- | --- |
114
268
  | `manual` | Check only when you call the APIs yourself. Default. |
115
269
  | `immediate` | Download and apply a new bundle right away. |
116
- | `on-next-launch` | Stage the update now, apply it on the next cold launch. |
270
+ | `on-next-launch` | Stage the update now, then apply it on the next cold launch. |
117
271
 
118
- `on-next-launch` is the safest choice for most apps: users never see a reload
119
- mid-session, and the update is already on-device the next time they open the app.
120
-
121
- ---
272
+ `on-next-launch` is a good default for most apps: users do not see a reload in the
273
+ middle of a session, and the update is ready for the next launch.
122
274
 
123
275
  ## Driving Updates Manually
124
276
 
125
- For custom "Update available" UI, use the `useBundleDrop()` hook. It subscribes to
126
- the singleton runtime and exposes actions plus live state:
277
+ For custom update UI, use the `useBundleDrop()` hook. It subscribes to the singleton
278
+ runtime and exposes actions plus live state:
127
279
 
128
280
  ```tsx
281
+ import { Button } from 'react-native';
129
282
  import { useBundleDrop } from '@gfean/react-native-bundle-drop';
130
283
 
131
284
  function UpdateBanner() {
@@ -150,9 +303,8 @@ function UpdateBanner() {
150
303
  ```
151
304
 
152
305
  The same actions are available as standalone functions (`checkForUpdate`,
153
- `downloadUpdate`, `applyUpdate`, `setChannel`, `reportHealthy`, …) for use outside React.
154
-
155
- ---
306
+ `downloadUpdate`, `applyUpdate`, `setChannel`, `reportHealthy`, and others) for use
307
+ outside React.
156
308
 
157
309
  ## Targeted Rollouts
158
310
 
@@ -170,56 +322,44 @@ Property values must be strings, finite numbers, or booleans. Keys are trimmed a
170
322
  must be non-empty, 128 characters or fewer, and cannot start with `$`, contain `.`,
171
323
  contain a null byte, or use reserved prototype names.
172
324
 
173
- ---
174
-
175
325
  ## Hybrid OTA Delivery
176
326
 
177
327
  Bundle Drop installs complete, immutable bundle folders, each identified by a
178
- canonical `bundleHash` for the full reconstructed file tree. Patch transports are
179
- purely a download optimization: the SDK reconstructs the complete target folder,
180
- validates the manifest contract in JS, verifies file hashes and sizes with native
181
- batch verification, then promotes `bundle-drop/bundles/{bundleHash}`.
182
-
183
- The result is **full-bundle reliability with patch-sized downloads**: you get the
184
- integrity guarantees of shipping a whole bundle, without making every device
185
- re-download everything on each release.
186
-
187
- - The SDK always supports `asset-only-v1` patch sets and advertises `xdelta3-vcdiff`
188
- when native xdelta support passes its probe.
189
- - When patch transport is unavailable or fails, the SDK falls back to the signed full ZIP.
190
- - Rollback stays a local pointer switch between already-verified bundle hashes.
328
+ canonical `bundleHash` for the reconstructed file tree. Patch transport is a download
329
+ optimization: the SDK reconstructs the complete target folder, validates the
330
+ manifest, verifies file hashes and sizes, and only then promotes the bundle.
191
331
 
192
- The current production manifest contract is `manifestVersion: 1`. This is not a
193
- legacy compatibility mode — it is the only accepted canonical manifest. `jsBundleHash`
194
- is retained as metadata only.
332
+ - The SDK supports `asset-only-v1` patch sets and advertises `xdelta3-vcdiff` when
333
+ native xdelta support passes its probe.
334
+ - If patch transport is unavailable or fails, the SDK falls back to the signed
335
+ full ZIP.
336
+ - Rollback remains a local pointer switch between verified bundle hashes.
195
337
 
196
- ---
338
+ The production manifest contract is `manifestVersion: 1`. `jsBundleHash` is retained
339
+ as metadata only.
197
340
 
198
341
  ## Observability
199
342
 
200
- OTA shouldn't blind your crash reporter. Every bundle has a unique hash, and
201
- `bundle-drop upload --sourcemap` produces source maps alongside the bundle so stack
202
- traces stay accurate across every update. Use `getObservabilityContext()` to tag
203
- error reports with the currently running bundle:
343
+ Every bundle has a unique hash, and `bundle-drop upload --sourcemap` produces source
344
+ maps so stack traces remain attributable across updates. Use
345
+ `getObservabilityContext()` to tag error reports with the running bundle:
204
346
 
205
347
  ```ts
206
348
  import { getObservabilityContext } from '@gfean/react-native-bundle-drop';
207
349
 
208
- const context = await getObservabilityContext(); // e.g. attach to Sentry/Bugsnag scope
350
+ const context = await getObservabilityContext();
209
351
  ```
210
352
 
211
- Works with Sentry, Bugsnag, Datadog, or any error tracker. See the
353
+ This works with Sentry, Bugsnag, Datadog, and other error trackers. See the
212
354
  [observability guide](https://bundledrop.app/docs/observability). Apps on
213
- `@sentry/react-native` 7.8.x that combine Sentry's Metro wrapper with Hermes
214
- should follow the guide's
355
+ `@sentry/react-native` 7.8.x that combine Sentry's Metro wrapper with Hermes should
356
+ follow the guide's
215
357
  [Sentry/Hermes OTA setup](https://bundledrop.app/docs/observability#sentry-and-hermes-ota-builds)
216
358
  to keep content-derived Debug IDs from inflating binary patches.
217
359
 
218
- ---
219
-
220
360
  ## API Reference
221
361
 
222
- Import from `@gfean/react-native-bundle-drop`.
362
+ Import the runtime API from `@gfean/react-native-bundle-drop`.
223
363
 
224
364
  **Runtime controller**
225
365
 
@@ -234,69 +374,55 @@ Import from `@gfean/react-native-bundle-drop`.
234
374
 
235
375
  | Option | Type | Default | Description |
236
376
  | --- | --- | --- | --- |
237
- | `environment` | `string` | — (required) | App environment shown in analytics, e.g. `production`, `staging`, `development`. |
238
- | `enabled` | `boolean` | `true` | When `false`, the SDK stays configured but fully no-ops. |
239
- | `channelName` | `string` | config `defaultChannel` (`develop`) | Initial OTA channel for this process. |
377
+ | `environment` | `string` | Required | App environment shown in analytics, such as `production`, `staging`, or `development`. |
378
+ | `enabled` | `boolean` | `true` | When `false`, the SDK stays configured but does not check, download, or apply. |
379
+ | `channelName` | `string` | Config `defaultChannel` (`develop`) | Initial OTA channel for this process. |
240
380
  | `policy` | `'manual' \| 'immediate' \| 'on-next-launch'` | `'manual'` | Startup behavior after hydration. |
241
- | `checkOnly` | `boolean` | `false` | Startup performs only a resolve/check, never download/apply. |
381
+ | `checkOnly` | `boolean` | `false` | Startup resolves updates without downloading or applying them. |
242
382
  | `onStatusUpdate` | `(status: string) => void` | — | Listener for human-readable status messages. |
243
383
 
244
- **Update actions** — `checkForUpdate`, `downloadUpdate`, `installBundle`, `applyUpdate`, `getUpdateState`, `getInstalledBundleInfo`, `getAvailableBundles`, `getAvailableChannels`.
384
+ **Update actions** — `checkForUpdate`, `downloadUpdate`, `installBundle`,
385
+ `applyUpdate`, `getUpdateState`, `getInstalledBundleInfo`, `getAvailableBundles`,
386
+ `getAvailableChannels`.
245
387
 
246
- **React** — `useBundleDrop()` → live state (`status`, `isEnabled`, `isBusy`, `channelName`, `installedInfo`, `pendingApply`, `hasBundle`, `availableChannels`) plus the action functions above.
388
+ **React** — `useBundleDrop()` returns live state (`status`, `isEnabled`, `isBusy`,
389
+ `channelName`, `installedInfo`, `pendingApply`, `hasBundle`, `availableChannels`)
390
+ plus update actions.
247
391
 
248
- **User properties** — `setUserProperty`, `removeUserProperty`, `getUserProperties`, `getCurrentUserProperties`, `resetUserProperties`.
392
+ **User properties** — `setUserProperty`, `removeUserProperty`, `getUserProperties`,
393
+ `getCurrentUserProperties`, `resetUserProperties`.
249
394
 
250
395
  **Errors** — `BundleDropError`, `isBundleDropError`.
251
396
 
252
- **CLI** (`npx bundle-drop <command>`) — `login`, `logout`, `whoami`, `init`, `init-native`, `init-metro`, `upload <ios|android>`.
397
+ **Metro** — import `withBundleDropExpo` from
398
+ `@gfean/react-native-bundle-drop/metro` when configuring Expo Metro manually.
253
399
 
254
- ---
255
-
256
- ## Requirements
400
+ **CLI** (`npx bundle-drop <command>`) — `login`, `logout`, `whoami`, `init`,
401
+ `doctor`, `eas-receipt <ios|android>`, and `upload <ios|android>`.
257
402
 
258
- - Bare React Native on iOS and Android (`react-native >= 0.71`, `react >= 17`).
259
- - iOS 13.0 or newer.
260
- - A Bundle Drop account and project (`npx bundle-drop login && npx bundle-drop init`).
403
+ ## Good to Know
261
404
 
262
- ---
405
+ - **OTA covers JavaScript and assets, not native code.** Native modules, native
406
+ dependency upgrades, permissions, native configuration, and React Native upgrades
407
+ require a new store binary.
408
+ - **Follow store policies.** Use OTA delivery for changes that remain within Apple
409
+ and Google requirements and the purpose of the reviewed app.
410
+ - **Compatibility checks are deliberate.** A device does not receive an update
411
+ built for a different app or runtime version.
412
+ - **Release builds run installed OTAs.** Expo Go, Debug builds, and development
413
+ clients continue to use their development JavaScript source.
414
+ - **Bundle Drop complements crash reporting.** It provides release identity and
415
+ source-map support; it does not replace an error tracker.
263
416
 
264
- ## Good To Know
265
-
266
- Bundle Drop is an OTA delivery system for React Native, not a magic bypass of how
267
- mobile apps work. A few things to keep in mind so it works the way you expect:
268
-
269
- - **OTA covers JavaScript and assets, not native code.** Anything that changes the
270
- native binary — new native modules, native dependency upgrades, permission or
271
- config changes, a React Native version bump — still ships through a normal App
272
- Store / Play Store release. Bundle Drop updates run on top of that native binary.
273
- - **Use it within store policies.** Over-the-air updates are meant to fix bugs and
274
- improve the app you already shipped, not to change its core purpose or sneak in
275
- behavior that would fail review. Ship responsibly and stay within Apple and Google
276
- guidelines.
277
- - **Version gating is a feature, not a bug.** A JS bundle is only delivered to
278
- binaries it's compatible with. If a device is on an older native build, it won't
279
- receive an incompatible update — that's what keeps rollouts safe.
280
- - **It's a hosted service.** Bundle Drop needs its backend and your project to
281
- resolve, sign, and serve bundles. It is not a zero-backend, offline-only tool.
282
- - **Native changes need a rebuild.** Updating this package's native code requires
283
- rebuilding the host app; `nativeVersion` tracks that boundary (bump it → run `pod install`).
284
- - **It is not a crash reporter.** Bundle Drop keeps your existing error tracker
285
- accurate across OTA updates; it doesn't replace Sentry, Bugsnag, or Datadog.
286
- - **Not for the Expo Go / managed workflow.** You need a native build (bare RN or an
287
- Expo prebuild) to install the native module.
288
-
289
- ---
290
-
291
- ## Docs & Links
417
+ ## Docs and Links
292
418
 
293
419
  - Website: [bundledrop.app](https://bundledrop.app)
294
420
  - Docs: [bundledrop.app/docs](https://bundledrop.app/docs)
295
421
  - Dashboard: [developer.bundledrop.app](https://developer.bundledrop.app)
296
422
  - Migrating from CodePush: [bundledrop.app/codepush-alternative](https://bundledrop.app/codepush-alternative)
297
423
  - Issues: [github.com/GFean/react-native-bundle-drop/issues](https://github.com/GFean/react-native-bundle-drop/issues)
298
-
299
- ---
424
+ - Security: [SECURITY.md](SECURITY.md)
425
+ - Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
300
426
 
301
427
  ## License
302
428
 
@@ -3,6 +3,7 @@ package com.bundledrop
3
3
  import android.content.Context
4
4
  import android.util.Log
5
5
  import java.io.File
6
+ import org.json.JSONObject
6
7
 
7
8
  /**
8
9
  * Resolves the on-disk OTA JS bundle path (no React / bridge types).
@@ -12,8 +13,22 @@ import java.io.File
12
13
  */
13
14
  object BundleDropNativePaths {
14
15
  private const val KEY_BINARY_VERSION = "binary_version"
16
+ private const val BUILD_IDENTITY_ASSET = "bundle-drop/build-identity.json"
15
17
 
16
- private fun getBinaryVersionKey(context: Context): String {
18
+ internal fun binaryVersionKey(
19
+ versionName: String,
20
+ versionCode: Long,
21
+ runtimeVersion: String?,
22
+ ): String {
23
+ val binaryVersion = "$versionName-$versionCode"
24
+ return if (runtimeVersion?.trim().isNullOrEmpty()) {
25
+ binaryVersion
26
+ } else {
27
+ "runtime:$runtimeVersion|binary:$binaryVersion"
28
+ }
29
+ }
30
+
31
+ private fun getBinaryVersionKey(context: Context, runtimeVersion: String?): String {
17
32
  val pInfo = context.packageManager.getPackageInfo(context.packageName, 0)
18
33
  val versionName = pInfo.versionName ?: "unknown"
19
34
  @Suppress("DEPRECATION")
@@ -22,7 +37,19 @@ object BundleDropNativePaths {
22
37
  } else {
23
38
  pInfo.versionCode.toLong()
24
39
  }
25
- return "$versionName-$versionCode"
40
+ return binaryVersionKey(versionName, versionCode, runtimeVersion)
41
+ }
42
+
43
+ internal fun readEmbeddedRuntimeVersion(context: Context): String? {
44
+ return try {
45
+ context.assets.open(BUILD_IDENTITY_ASSET).bufferedReader().use { reader ->
46
+ JSONObject(reader.readText())
47
+ .optString("runtimeVersion", "")
48
+ .takeIf { it.trim().isNotEmpty() }
49
+ }
50
+ } catch (_: Exception) {
51
+ null
52
+ }
26
53
  }
27
54
 
28
55
  private fun getStoredBinaryVersion(context: Context): String? {
@@ -38,12 +65,15 @@ object BundleDropNativePaths {
38
65
  @JvmStatic
39
66
  fun getDownloadedBundlePath(context: Context): String? {
40
67
  if (!BundleDropOtaPrefs.isOtaEnabled(context)) return null
68
+ return getDownloadedBundlePath(context, readEmbeddedRuntimeVersion(context))
69
+ }
41
70
 
71
+ internal fun getDownloadedBundlePath(context: Context, runtimeVersion: String?): String? {
42
72
  val bundleDropRoot = File(context.filesDir, "bundle-drop")
43
73
  val result = BundleDropOtaResolver.resolve(
44
74
  bundleDropRoot = bundleDropRoot,
45
75
  filesDir = context.filesDir,
46
- currentBinaryVersion = getBinaryVersionKey(context),
76
+ currentBinaryVersion = getBinaryVersionKey(context, runtimeVersion),
47
77
  storedBinaryVersion = getStoredBinaryVersion(context),
48
78
  )
49
79
 
package/app.plugin.js ADDED
@@ -0,0 +1,3 @@
1
+ 'use strict';
2
+
3
+ module.exports = require('./plugin');