@gfean/react-native-bundle-drop 0.11.0 → 0.12.1

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.
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # Bundle Drop
1
+ # Bundle Drop — React Native and Expo OTA updates
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/%40gfean%2Freact-native-bundle-drop?color=2b7fff&label=npm)](https://www.npmjs.com/package/@gfean/react-native-bundle-drop)
4
4
  [![CI](https://github.com/GFean/react-native-bundle-drop/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/GFean/react-native-bundle-drop/actions/workflows/ci.yml)
@@ -7,921 +7,166 @@
7
7
  [![docs](https://img.shields.io/badge/docs-bundledrop.app%2Fdocs-0f766e)](https://bundledrop.app/docs)
8
8
  [![dashboard](https://img.shields.io/badge/dashboard-developer.bundledrop.app-111827)](https://developer.bundledrop.app)
9
9
 
10
- **Ship reliable over-the-air updates to Expo and bare React Native apps.**
10
+ **Bundle Drop is an over-the-air (OTA) update platform for Expo and bare React Native.** The SDK and CLI ship JavaScript and bundled assets to compatible iOS and Android release builds. Use channels and staged rollouts to control who receives an update, patch downloads to reduce transfer size, and bundle hashes to match crash reports to the code that ran.
11
11
 
12
- Bundle Drop delivers JavaScript and asset updates to compatible iOS and Android
13
- binaries, with channel-based releases, targeted rollouts, rollback safety, and
14
- patch-sized downloads.
12
+ [CodePush alternative](https://bundledrop.app/codepush-alternative) · [Bundle Drop Sight](https://bundledrop.app/sight)
15
13
 
16
- [Website](https://bundledrop.app) • [Docs](https://bundledrop.app/docs) • [Dashboard](https://developer.bundledrop.app) • [Coming from CodePush?](https://bundledrop.app/codepush-alternative)
14
+ ## Quick start
17
15
 
18
- ---
19
-
20
- ## Why Bundle Drop?
21
-
22
- Shipping a JavaScript or asset fix should not always require a new native build.
23
-
24
- | Native release workflow | With Bundle Drop |
16
+ | Requirement | Supported |
25
17
  | --- | --- |
26
- | Rebuild the app for every JavaScript or asset change. | Publish OTA-compatible changes from your machine or CI. |
27
- | Wait for users to install the next store version. | Compatible devices can receive an update on their next check. |
28
- | Leave a faulty release active until another binary ships. | Stop a rollout or return to a verified bundle quickly. |
29
-
30
- Bundle Drop only delivers updates that match the installed app's native and
31
- runtime identity. Native changes still require a new App Store or Play Store build.
32
-
33
- ---
18
+ | Expo | SDK 54–57 |
19
+ | Bare React Native | 0.71+ |
20
+ | Platforms | iOS and Android, including legacy and New Architecture |
21
+ | Node.js | 20.19.4+ for package installation and CLI use |
22
+ | React | Match your app's React Native or Expo version. `useBundleDrop()` requires React 18+. |
34
23
 
35
- ## Features
36
-
37
- - **Expo and bare React Native support** — use the Expo config plugin or native
38
- React Native autolinking.
39
- - **Channel-based distribution** — ship to `develop`, `production`, `beta`, or any channel you define.
40
- - **Targeted rollouts** — stage releases and target specific cohorts with user properties.
41
- - **Rollback safety** — every install is a verified, immutable bundle; rollback is a local pointer switch.
42
- - **Hybrid OTA transport** — keep full-bundle integrity while supported devices download patch-sized changes.
43
- - **Runtime gating** — updates only reach compatible native binaries.
44
- - **Observability metadata** — bundle hashes and source maps keep crash reports attributable to the correct release.
45
- - **CI/CD support** — upload with a Personal Access Token from any pipeline.
46
- - **Bundle Drop Sight** — inspect JavaScript bundle sizes locally, including
47
- working-tree comparisons against a Git baseline.
48
-
49
- ## Compatibility
50
-
51
- | Surface | Supported versions |
52
- | --- | --- |
53
- | Expo | SDK 54, 55, 56, and 57 |
54
- | Bare React Native | React Native 0.71 and newer |
55
- | Platforms | iOS and Android |
56
- | Architectures | Legacy architecture and New Architecture |
57
- | Node.js | 20.19.4 or newer |
58
- | React | 17 or newer |
24
+ ### 1. Install the package
59
25
 
60
- The Node requirement applies to installation of the package, including projects
61
- that use only the mobile SDK. Development and
62
- package builds use Node 22.13.0, as specified in `.nvmrc`.
63
-
64
- Run `bundle-drop --help` to browse commands grouped into Setup, Analysis,
65
- Releases, and Account. Existing command names and flags remain unchanged.
66
- For iOS metadata, `--plist-file` and Sight accept XML Info.plist files; binary
67
- and OpenStep property lists are not supported.
68
-
69
- ## Installation
70
-
71
- ### Expo
72
-
73
- Install the package with Expo's version-aware installer:
26
+ For Expo:
74
27
 
75
28
  ```bash
76
29
  npx expo install @gfean/react-native-bundle-drop
77
30
  ```
78
31
 
79
- Bundle Drop's setup command registers the config plugin and preserves your existing
80
- Expo Metro configuration.
81
-
82
- ### Bare React Native
83
-
84
- Install with your package manager:
32
+ For bare React Native:
85
33
 
86
34
  ```bash
87
35
  npm install @gfean/react-native-bundle-drop
88
- # or
89
- yarn add @gfean/react-native-bundle-drop
90
- ```
91
-
92
- Then install the iOS pod:
93
-
94
- ```bash
95
- cd ios && pod install
96
- ```
97
-
98
- React Native autolinking handles the package on both platforms. The setup command
99
- adds the app-entry integration that allows a Release build to start an installed OTA.
100
-
101
- ## Bundle Drop Sight
102
-
103
- Sight analyzes production JavaScript bundles and emitted assets in your browser. It
104
- does not require a Bundle Drop account, OTA project configuration, login, or native
105
- integration. Run it from the app directory containing `package.json`:
106
-
107
- ```bash
108
- npx bundle-drop sight --platform android
109
- npx bundle-drop sight --compare main --platform android
110
- npx bundle-drop sight --compare origin/main --fetch --platform ios
111
- ```
112
-
113
- The first command analyzes the current app using its installed dependencies and
114
- includes emitted assets through the automatic CLI handoff.
115
- `--compare` builds both an explicit Git baseline and a captured copy of your current
116
- working tree. Both builds run locally, including when the baseline is a remote
117
- tracking branch. Sight compares **raw UTF-8 bytes in minified JavaScript** and uses
118
- source maps to attribute changes to packages and files. Both CLI modes include a
119
- **Bundled assets** breakdown for files emitted by the same Metro/Expo build, such as
120
- images and fonts. Assets do not change the JavaScript totals or treemap.
121
-
122
- **Bundle Drop OTA size** measures a locally generated full OTA archive using Bundle Drop's
123
- canonical packaging. Each revision uses its own JavaScript engine configuration:
124
- Hermes is compiled with project-local tooling when enabled. JavaScript attribution
125
- and raw asset sizes remain separate; they are not bytecode attribution.
126
-
127
- Bare iOS upload and Sight honor explicit Bundle Drop and native Hermes settings first.
128
- For the standard React Native **0.81.x** template, they also recognize the installed
129
- React Native helpers' implicit Hermes default when those helpers match the verified
130
- 0.81.5 files. This conservative fallback is skipped
131
- for custom engine configuration, community JSC indicators, or unfamiliar templates
132
- and versions. For a custom project, set `hermesBytecode: { ios: true }` (or `false`
133
- for JavaScript) in `bundle.drop.config.js` to match the engine in your native app.
134
- The fallback does not evaluate Ruby or change your Podfile.
135
-
136
- Measurement adds compilation and archive compression after the JavaScript build, once
137
- per side in a comparison. Expo's Hermes path also performs a separate bytecode
138
- export to preserve its upload-specific minification behavior. It requires a resolvable app/runtime identity. When that
139
- identity or required compiler is unavailable, Sight keeps the JavaScript and asset
140
- analysis and marks the OTA measurement unavailable with a reason. It never fills in
141
- an estimated archive size. Comparing this metric requires Bundle Drop to be configured
142
- on both branches with a resolvable app/runtime identity. The archive describes the selected Sight entry and build
143
- environment; upload overrides or different inputs can produce another size.
144
-
145
- Asset sizes count each emitted output file once, including emitted density variants.
146
- Identical contents at different output paths count separately; a changed hash at the
147
- same path is a change even when the byte size is unchanged. Only emitted files are
148
- counted, not every asset in the repository. Native-only resources and network-loaded
149
- assets are outside this measurement. The OTA archive includes delivery metadata and asset
150
- manifests, and excludes source maps. It is not APK/IPA size. File size changes do
151
- not measure startup time or memory use.
152
-
153
- No native app build is needed for asset analysis or comparison. The existing JavaScript bundling
154
- step emits the files into private temporary directories; the CLI records relative
155
- output paths, byte lengths, and SHA-256 hashes, then removes the emitted asset copies.
156
- Only the inventory is passed to Sight, with no image previews or binary asset uploads.
157
- This collection code stays in the CLI and adds no runtime dependencies or mobile SDK
158
- code.
159
-
160
- The CLI transfers the generated files to Sight through a short-lived loopback
161
- session. Source code, bundles, source maps, and comparison metadata are not uploaded
162
- to Bundle Drop servers. Loading the Sight web page still needs browser access to
163
- `bundledrop.app`.
164
-
165
- ### Comparison options
166
-
167
- | Option | Behavior |
168
- | --- | --- |
169
- | `--compare <ref>` | Resolve a branch, tag, or commit to an immutable baseline commit before building. |
170
- | `--fetch` | Refresh the explicitly named remote branch, such as `origin/main`, using ordinary Git credentials. Requires `--compare`. |
171
- | `--platform ios\|android` | Compare one platform per invocation. If ambiguous, interactive use prompts; noninteractive use requires the flag. |
172
- | `--project-type bare\|expo` | Override project detection consistently for both sides. |
173
- | `--entry-file <path>` | Choose an app-relative entry file that must exist in both snapshots. |
174
- | `--include <path>` | Copy an extra local file or directory identically into both snapshots; repeat for multiple inputs. |
175
- | `--no-open` | Keep the generated files and print manual browser instructions. |
176
- | `--keep` | Keep the comparison files after a successful browser transfer. |
177
- | `--output <path>` | Write persistent output to an empty directory. |
178
-
179
- Without `--fetch`, Sight uses locally available refs and does not contact a Git
180
- remote. `main` is never silently substituted with `origin/main`. Explicit refresh
181
- requires a configured remote branch; use normal Git commands first to obtain a
182
- missing tag, commit, or additional shallow history. Sight neither requests nor
183
- stores repository credentials.
184
-
185
- ### What each side builds
186
-
187
- The current snapshot contains tracked working-tree contents, including uncommitted
188
- edits and deletions, plus nonignored untracked files. Ignored inputs such as local
189
- environment files are excluded unless explicitly included:
190
-
191
- ```bash
192
- npx bundle-drop sight --compare main --platform android \
193
- --include .env.production --include local-build-config
194
- ```
195
-
196
- Included paths must stay inside the repository. They cannot overwrite files
197
- tracked on either side or supply dependency manifests, lockfiles, or installed
198
- dependencies. The same captured contents are added to both sides, so the baseline
199
- remains a comparison under the same explicitly supplied local configuration.
200
-
201
- Sight creates private temporary Git worktrees for the two builds. Both have a
202
- detached `HEAD`: baseline points at the resolved baseline commit, and current
203
- points at your original `HEAD` with captured working-tree files overlaid. Your
204
- original staging partition is not reproduced; scripts that distinguish staged
205
- from unstaged changes, or depend on an attached branch name, may behave differently.
206
- Sight does not switch, stash, reset, or stage your original checkout.
207
-
208
- The private repository has independent object storage and preserves the captured
209
- local branch/tag/remote-tracking refs and available history. `git rev-parse HEAD`
210
- and ancestry queries use each side's own commit. `git describe` evaluates the
211
- captured tags from that commit; these are today's locally available refs, not
212
- their historical state at the baseline date. Missing shallow history or tags may
213
- change its output, and Sight does not fetch them implicitly. Branch-name queries
214
- observe detached HEAD; the original branch label is metadata only.
215
-
216
- `git describe --dirty` reflects each private worktree, including explicit includes
217
- and build-script changes. Original dirty status is recorded separately. Builds
218
- depending on attached branches or staging partitions must accommodate these
219
- semantics through their existing configuration/environment. Sight verifies pinned
220
- HEADs and refs around build phases and rejects mutations that invalidate provenance.
221
- It rechecks captured files, modes, symlinks, HEAD, and index for observed concurrent
222
- changes; the copy is not an atomic filesystem snapshot.
223
-
224
- Both sides use the same Node executable, platform, production/minification settings,
225
- and logical entrypoint. Each revision retains its own dependencies and bundler
226
- configuration. Sight records framework/package-manager versions and warns when
227
- relevant inputs differ. A framework upgrade or configuration change can legitimately
228
- affect the result. Required environment variables must be available to both builds;
229
- there is no automatic fallback from a failed build to the other revision's output.
230
-
231
- ### Dependencies and supported repository layouts
232
-
233
- Comparison installs fresh dependencies for each side from its own lockfile. It
234
- supports npm, pnpm, Yarn Classic, and modern Yarn with `nodeLinker: node-modules`.
235
- An exact `packageManager` declaration must match the available executable; tracked
236
- `yarnPath` configurations are honored. Without a declaration, a unique lockfile
237
- family selects the available manager and its actual version is recorded. Sight
238
- does not automatically download package-manager binaries or change a lockfile to
239
- make installation succeed.
240
-
241
- Dependency installation can access package registries and execute project lifecycle
242
- scripts. Existing script policies are preserved. For declared `engines.node` ranges,
243
- Sight uses the installed `npm` executable to check a temporary dependency-free
244
- manifest with an offline, script-disabled dry run before the real installs. This
245
- check also requires npm when the project uses Yarn or pnpm. Build/configuration
246
- scripts execute as ordinary local processes; the temporary worktrees are not a
247
- security sandbox for untrusted project code.
248
-
249
- Apps in a single npm, Yarn, or pnpm workspace root can use other packages inside
250
- the same Git repository. Installation runs at the workspace root; bundling runs
251
- from the app directory. Nested/ambiguous workspace roots, nested app lockfiles,
252
- external local dependencies or symlinks, Bun, and Plug'n'Play installations are not
253
- supported. npm workspaces require a v2 or newer lockfile. Unresolved Git conflicts,
254
- sparse/partial clones, required Git submodules, Git LFS/checkout filters, and tracked
255
- `node_modules` are also unsupported. There is no comparison build or dependency-tree
256
- cache in this version.
257
-
258
- Actual workspace frozen installs have been verified on macOS arm64 with Node
259
- 22.13.0 using npm 10.9.2, pnpm 11.24.0, Yarn 1.22.22, and Yarn 3.8.3. These installer
260
- checks cover a registry dependency, a local workspace dependency, lifecycle scripts,
261
- and unchanged manifests/lockfiles. Real comparisons were also verified with npm
262
- 10.9.2, React Native 0.83.1, and Expo 55.0.0: dirty source capture, package additions,
263
- identical inputs, and automatic browser attribution after source cleanup.
264
- An Expo Router 55.0.18 app also passed a real comparison using `expo-router/entry`.
265
- Windows/Linux hosts and full framework builds with pnpm or Yarn remain unverified;
266
- the installer checks alone do not establish those combinations.
267
-
268
- ### Keeping files and opening Sight manually
269
-
270
- ```bash
271
- npx bundle-drop sight --platform android --no-open --output ./sight-analysis
272
- npx bundle-drop sight --compare main --platform android \
273
- --no-open --output ./sight-comparison
274
- ```
275
-
276
- Single analysis keeps a bundle/source-map pair and `analysis-assets.json`, a local
277
- record of emitted paths, sizes, hashes, and the exact bundle/map hashes. The automatic
278
- CLI handoff verifies this binding before including assets in the analysis.
279
-
280
- Comparison output contains `baseline/` and `current/` bundle/source-map pairs plus
281
- `comparison.json` and `comparison-assets.json` as local records. Automatic CLI
282
- loading verifies these files and includes Git labels, build context, and asset
283
- sizes. The browser does not expose metadata or inventory upload controls.
284
-
285
- For a manual JavaScript-only comparison, open
286
- [Bundle Drop Sight](https://bundledrop.app/sight), select Compare, and attach the
287
- four bundle/map files. Manual Analyze still takes one bundle and its matching map;
288
- manual Compare still takes two pairs. Neither requires the Bundle Drop SDK or extra
289
- JSON files. Git labels and asset sizes appear only through the CLI handoff. Changing
290
- a file after a CLI handoff clears its comparison context.
291
-
292
- Comparison metadata remains limited to 64 KiB. Each asset inventory is limited to
293
- 4 MiB and 10,000 files per build; oversized inventories fail explicitly
294
- instead of producing partial totals. Inventory paths are output-relative and are
295
- never opened by the browser.
296
-
297
- Temporary worktrees and dependencies are removed after success, failure, or
298
- cancellation. Completed files from either CLI mode are retained when browser handoff
299
- fails; the CLI prints their location, and comparisons also print the diagnostics
300
- directory. `--keep`, `--no-open`, and `--output` retain the requested artifacts,
301
- including the local asset record. A failure before complete artifacts
302
- exist removes owned temporary output; explicitly requested output directories are
303
- kept for inspection.
304
-
305
- The metadata contains local temporary source roots so unchanged source maps remain
306
- attributable after cleanup. Sight excludes those roots from displayed/exported
307
- provenance and analytics. Manual file loading uses ordinary JavaScript comparison
308
- behavior without the CLI source-path context.
309
-
310
- Removal failures report the owned directory for manual recovery. An uncatchable
311
- termination, such as a forced process kill or power loss, can leave temporary
312
- `bundle-drop-sight-*` directories. After confirming the invocation and its build
313
- processes have stopped, remove only those reported/identified temporary directories;
314
- keep completed comparison output if it is still needed.
315
-
316
- On macOS/Linux, Sight stops ordinary child process groups before removing the
317
- worktrees, including background children left after a command exits. On Windows,
318
- cancellation uses `taskkill` for the active process tree, but this version has no
319
- Job Object containment: background descendants can survive if their parent has
320
- already exited. Scripts that deliberately detach into a separate process group
321
- also fall outside process-group cleanup.
322
-
323
- ## First-Time Setup
324
-
325
- Run these commands from your app's project root:
326
-
327
- ```bash
328
- npx bundle-drop login
329
- npx bundle-drop doctor
330
- ```
331
-
332
- `login` signs you in, creates `bundle.drop.config.js` when needed, pins the
333
- authenticated runtime-delivery bootstrap under `.bundle-drop/`, detects Expo or
334
- bare React Native, previews the integration changes, and completes setup. `doctor`
335
- then validates configuration, runtime identity, native integration, and startup
336
- ownership.
337
-
338
- Run `init` when you need to review or rerun setup. You can force project detection
339
- for unusual repository layouts:
340
-
341
- ```bash
342
- npx bundle-drop init
343
- npx bundle-drop init --project-type expo
344
- npx bundle-drop init --project-type bare
345
- ```
346
-
347
- Run `npx bundle-drop doctor` again after changing native integration, Metro, Expo
348
- configuration, or runtime versions.
349
36
 
350
- When Bundle Drop rotates manifest verification keys or changes the public manifest
351
- route, refresh the pinned client-visible bootstrap explicitly:
352
-
353
- ```bash
354
- npx bundle-drop sync
355
- npx bundle-drop doctor
356
- ```
357
-
358
- Apps upgrading from an inline `runtimeDelivery` block or a direct Metro alias should
359
- remove that stale block and run `npx bundle-drop init` once to install the
360
- package-managed Metro wrapper. Inline delivery data is ignored: the validated
361
- runtime-delivery lockfile is the sole trust source. After that one-time migration, `sync`
362
- is the narrow command for refreshing trust data.
363
-
364
- The runtime-delivery lockfile is not a secret and should be committed. Setup keeps the
365
- generated Metro wrapper, build receipts, and other transient `.bundle-drop` files
366
- ignored while allowing `.bundle-drop/runtime-delivery.lock.json` into source
367
- control. Projects with the former `runtime-delivery.generated.json` filename remain
368
- readable; run `bundle-drop sync` to migrate and remove that legacy file.
369
-
370
- ### Manual setup without AI planning
371
-
372
- You can configure Bundle Drop without sending project files to the AI setup planner.
373
- Create `bundle.drop.config.js` with the project identity and public project API key
374
- shown in the developer dashboard:
375
-
376
- ```js
377
- module.exports = {
378
- serverUrl: 'https://api.bundledrop.app',
379
- defaultChannel: 'develop',
380
- runtimeVersion: { ios: '1.0.0', android: '1.0.0' },
381
- org: { slug: 'your-org' },
382
- project: {
383
- name: 'Your App',
384
- slug: 'your-app',
385
- apiKey: 'your-public-project-key',
386
- },
387
- };
37
+ # iOS only
38
+ (cd ios && pod install)
388
39
  ```
389
40
 
390
- Wrap the final exported Metro config. For bare React Native:
41
+ ### 2. Configure your project
391
42
 
392
- ```js
393
- const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
394
- const { withBundleDrop } = require('@gfean/react-native-bundle-drop/metro');
395
-
396
- const config = mergeConfig(getDefaultConfig(__dirname), {});
397
- module.exports = withBundleDrop(config, { projectRoot: __dirname });
398
- ```
399
-
400
- For Expo:
401
-
402
- ```js
403
- const { getDefaultConfig } = require('expo/metro-config');
404
- const { withBundleDropExpo } = require('@gfean/react-native-bundle-drop/metro');
405
-
406
- module.exports = withBundleDropExpo(getDefaultConfig(__dirname), {
407
- projectRoot: __dirname,
408
- });
409
- ```
410
-
411
- Expo projects must also add `@gfean/react-native-bundle-drop` to the app config's
412
- `plugins` array. Bare projects must connect Bundle Drop to the Release bundle URL in
413
- their Android and iOS entrypoints. Follow the
414
- [manual native setup guide](https://bundledrop.app/docs/manual-setup) because the
415
- entrypoint shape varies across React Native versions.
416
-
417
- Finish every manual setup by authenticating, generating the public trust bootstrap,
418
- and validating the complete integration:
43
+ Create an organization and project in the developer dashboard. Then run these commands from the app root:
419
44
 
420
45
  ```bash
421
46
  npx bundle-drop login
422
- npx bundle-drop sync
423
47
  npx bundle-drop doctor
424
48
  ```
425
49
 
426
- `sync` creates `.bundle-drop/runtime-delivery.lock.json`, recreates it if it or
427
- the entire `.bundle-drop` directory was deleted, and repairs the corresponding
428
- `.gitignore` rules. The lockfile contains public identity and verification material,
429
- not secrets, so commit it with the application.
430
-
431
- ## Binary build numbers
432
-
433
- Uploads can record Android `versionCode` or iOS `CFBundleVersion` as optional
434
- display metadata. The dashboard shows it as `1.0.0 (122132)`. Expo uses its resolved
435
- build identity; bare projects use recognized literal Gradle/plist/Xcode settings.
436
- For custom bare build scripts, pass `--build-number 122132` with the upload. Unknown
437
- or ambiguous values stay absent. Build numbers describe upload context and do not
438
- restrict delivery or replace runtime compatibility checks.
50
+ Review the setup plan before applying it. The CLI detects Expo or bare React Native, sets up Metro and native integration, and writes the project's public runtime-delivery trust lockfile. Commit `.bundle-drop/runtime-delivery.lock.json` with the app. Run `npx bundle-drop init` to rerun setup. For custom projects or setup without AI assistance, follow the [manual setup guide](https://bundledrop.app/docs/manual-setup).
439
51
 
440
- ## Native fingerprinting (Beta)
52
+ ### 3. Initialize the SDK and build a release
441
53
 
442
- Opt into native fingerprinting to derive `runtimeVersion` from native inputs
443
- instead of manually bumping it. Compatible JavaScript updates retain the identity;
444
- detected native changes create a different one and require a new native binary.
445
- Ship a fingerprint-enabled binary first. Manual runtimes remain the default.
446
-
447
- You can also keep an explicit runtime version as a manual boundary alongside the
448
- fingerprint. See [configuration, compatibility rules and coverage limits](docs/native-fingerprint.md).
449
-
450
- ## Initialize the Runtime
451
-
452
- Call `BundleDrop.init` once, as early as possible in the app process.
453
-
454
- ### Expo Router
455
-
456
- Initialize in `app/_layout.tsx`, before rendering the root layout:
457
-
458
- ```tsx
459
- import { BundleDrop } from '@gfean/react-native-bundle-drop';
460
- import { Stack } from 'expo-router';
461
-
462
- BundleDrop.init({
463
- enabled: !__DEV__,
464
- environment: __DEV__ ? 'development' : 'production',
465
- channelName: 'develop',
466
- policy: 'on-next-launch',
467
- });
468
-
469
- export default function RootLayout() {
470
- return <Stack />;
471
- }
472
- ```
473
-
474
- ### Conventional React Native entrypoint
475
-
476
- Initialize near the top of your entry file, before registering the root component:
54
+ Call `BundleDrop.init()` once near the app entry point. Put it before root registration in bare React Native or at module scope in the Expo Router root layout.
477
55
 
478
56
  ```tsx
479
- import { AppRegistry } from 'react-native';
480
57
  import { BundleDrop } from '@gfean/react-native-bundle-drop';
481
58
 
482
- import App from './App';
483
- import { name as appName } from './app.json';
484
-
485
59
  BundleDrop.init({
486
60
  enabled: !__DEV__,
487
61
  environment: __DEV__ ? 'development' : 'production',
488
62
  channelName: 'develop',
489
63
  policy: 'on-next-launch',
490
64
  });
491
-
492
- AppRegistry.registerComponent(appName, () => App);
493
65
  ```
494
66
 
495
- ## Expo Builds and Development
67
+ Build and install a Release binary with the Bundle Drop integration before testing OTA delivery. Use your usual native Release build or EAS Build profile. Expo Go, Debug builds, and development clients use their development JavaScript source. [Expo setup and build guide](https://bundledrop.app/docs/expo)
496
68
 
497
- Bundle Drop needs its native integration in the installed app. Expo Go does not
498
- contain that native adapter, so the SDK remains disabled there and your app can keep
499
- using Expo Go for normal development.
69
+ ### 4. Upload your first OTA update
500
70
 
501
- Debug builds and development clients also keep Metro as the JavaScript authority;
502
- they do not start an installed OTA bundle. Test the OTA lifecycle with a non-Debug
503
- Release build.
71
+ Make a small JavaScript or bundled asset change so you can see the update on the device.
504
72
 
505
- Implicit Expo Debug/Expo Go suppression applies only to the current process, so
506
- opening a development build does not disable OTA startup in a later Release build.
507
- An explicit `init({ enabled: false })` still persists the app's disabled setting.
508
- For Expo runtime fingerprints, setup excludes transient Kotlin compiler sessions
509
- under Gradle plugin and Android `.kotlin` directories. Rerun `bundle-drop init`
510
- and review its setup changes to add missing exclusions to an existing integration.
511
-
512
- For managed/CNG projects, setup can leave `ios/` and `android/` absent. The config
513
- plugin generates the native integration during a later prebuild, `expo run:*`, or
514
- EAS Build. Typical local Release builds are:
515
-
516
- ```bash
517
- npx expo run:ios --configuration Release
518
- npx expo run:android --variant release
519
- ```
520
-
521
- For remote builds, use your normal EAS profiles:
522
-
523
- ```bash
524
- eas build --platform ios
525
- eas build --platform android
526
- ```
527
-
528
- With the default literal runtime configuration, the plugin embeds the platform's
529
- literal in the native build and Expo uploads resolve that same literal directly from
530
- `bundle.drop.config.js`. This normal workflow does not require a build receipt.
531
-
532
- An advanced Expo project can explicitly make its Expo runtime policy authoritative
533
- with `runtimeVersion: { source: 'expo' }`. In that opt-in mode, uploads require an
534
- exact receipt from the matching local native build. For a remote EAS build, create an
535
- authenticated receipt from the completed build and pass the returned path to upload:
536
-
537
- ```bash
538
- npx bundle-drop eas-receipt ios --build-id <eas-build-id>
539
- npx bundle-drop upload ios --channel develop --build-receipt <receipt-path>
540
- ```
541
-
542
- Rebuild the native app whenever the config plugin, native dependencies, permissions,
543
- or runtime compatibility boundary changes.
544
-
545
- ### `expo-updates` startup ownership
546
-
547
- An active `expo-updates` installation can also own native startup, so it cannot be
548
- active in the same binary as Bundle Drop. Setup and `doctor` stop when they detect
549
- that conflict. To migrate intentionally, review the proposed changes and run:
550
-
551
- ```bash
552
- npx bundle-drop init --project-type expo --migrate-expo-updates
553
- ```
554
-
555
- This removes the active `expo-updates` integration and requires a new native binary.
556
- Do not publish a Bundle Drop update until that replacement binary has been built and
557
- distributed.
558
-
559
- ## Runtime Versions
560
-
561
- `bundle.drop.config.js` defines literal runtime versions shared by Expo and bare
562
- React Native projects:
563
-
564
- ```js
565
- module.exports = {
566
- // ...project configuration
567
- runtimeVersion: {
568
- ios: '1.0.0',
569
- android: '1.0.0',
570
- },
571
- };
572
- ```
573
-
574
- Keep a platform's literal unchanged for OTA-compatible JavaScript and asset updates.
575
- The upload will then target binaries built with that same runtime value.
576
-
577
- When native code or native configuration changes, bump the affected platform's
578
- literal and build a new binary before uploading updates for that runtime. For
579
- example, an iOS-only native change should bump `runtimeVersion.ios`; Android can keep
580
- its existing value. This makes the compatibility boundary explicit and prevents an
581
- update from reaching a binary that cannot run it.
582
-
583
- ## Native Startup Recovery
584
-
585
- Bundle Drop records every OTA startup attempt in native storage before React Native
586
- receives the bundle path. If an attempt does not reach its configured health boundary,
587
- the next distinct app launch counts it as incomplete. The candidate is retried until
588
- `rollback.maxCrashCount` is reached, then quarantined locally and replaced with the
589
- previous native-proven healthy OTA bundle. If that bundle is missing, corrupt,
590
- incompatible, or locally revoked, startup falls back to the bundle embedded in the app.
591
-
592
- Automatic health waits for React content to appear and then applies
593
- `rollback.healthyAfterSec`. Apps with a stronger readiness boundary can opt into
594
- `healthCheckMode: 'manual'` and call `BundleDrop.reportHealthy()` after hydration,
595
- migrations, authentication bootstrap, or navigation setup completes. Health is committed
596
- against the exact native launch attempt, so a delayed callback from an older React runtime
597
- cannot approve a newer launch.
598
-
599
- Recovery is local and offline; it never waits for a network request during startup. With
600
- `maxCrashCount: 0`, launch-health counting and automatic crash-loop rollback are disabled,
601
- while integrity, runtime compatibility, quarantine, and locally persisted revocation checks
602
- still apply. Native startup recovery requires a binary built with the corresponding SDK
603
- `nativeVersion`; it cannot be added to an older installed binary through OTA JavaScript.
604
- Crashes after an attempt is healthy do not trigger this rollback path and should use normal
605
- crash reporting plus fix-forward or explicit rollback controls.
606
-
607
- ## Managed Runtime Delivery
608
-
609
- Runtime delivery is package-managed. `bundle.drop.config.js` stays focused on
610
- application-owned values such as project identity, channel, runtime versions, and
611
- rollback policy; it does not contain manifest hosts, access routes, public keys, or
612
- a delivery-mode switch.
613
-
614
- `bundle-drop login` and `bundle-drop init` synchronize the trust bootstrap during
615
- setup. `bundle-drop sync` performs the same narrow operation later for repair or key
616
- rotation. Each command validates authenticated project credentials and writes the
617
- identity-bound `.bundle-drop/runtime-delivery.lock.json`. Metro confirms that
618
- the bootstrap belongs to the same server, organization, and project before merging
619
- it into the runtime module. Malformed, copied, unsupported, or private-key-bearing
620
- data is rejected.
621
-
622
- Older apps with an inline `runtimeDelivery` block keep their ordinary project
623
- configuration, but the inline block is ignored and should be removed during
624
- migration. Only the identity-bound runtime-delivery lockfile can enable managed delivery.
625
- If the server explicitly disables delivery for a project, synchronization removes a
626
- stale bootstrap and the SDK continues through the compatible `/ota/resolve` path.
627
-
628
- The SDK resolves a complete public lane locally. Invalid, expired, incomplete,
629
- dynamic, unavailable, or network-failed manifests safely fall back to `/ota/resolve`.
630
- Artifact download authorization remains API-key authenticated and uses opaque
631
- release and artifact references rather than URLs embedded in the manifest.
632
-
633
- Lane manifests are signed state and are not themselves the revocation clock. Every
634
- local check also fetches a small environment-wide signed publisher lease. The SDK
635
- verifies its key, exact manifest origin, issue time, and short absolute expiry before
636
- it verifies or persists lane generation state. A missing, invalid, expired, or
637
- operator-disabled lease therefore falls back to `/ota/resolve`, even when cached
638
- manifest bytes remain cryptographically valid.
639
-
640
- Managed artifact download capabilities are intentionally short-lived. If an artifact URL is
641
- rejected with HTTP 401 or 403 during download, the SDK reauthorizes the original
642
- signed selection once and retries only when its generation, target, transport,
643
- artifact references, and signed hashes are unchanged. Verification, reconstruction,
644
- and installation failures are never retried this way.
645
-
646
- With managed delivery, install through `downloadUpdate`, or use the React hook's
647
- `fetchBundles` and `installBundle(bundle)` list-item flow. Direct named
648
- `installBundle(hash, url, ...)` calls are rejected because they bypass the fresh
649
- resolve and artifact-authorization decision.
650
-
651
- Unchanged install state is reported at most once every seven days. A current bundle
652
- hash, app environment, or user-property change is reported immediately; successful
653
- installs continue to use the separate idempotent installed receipt.
654
- The SDK's bounded [installed receipt history](docs/install-report-deduplication.md)
655
- survives recovery to the embedded app without retaining stale installed metadata.
656
-
657
- The manifest URL is derived from `manifestBaseUrl`, `manifestAccessId`, channel,
658
- platform, and runtime version. `manifestAccessId` is an opaque URL-routing value,
659
- not a signing secret. `publicKeys` contains public P-256 JWK coordinates keyed by
660
- the manifest JWS `kid`, which permits signing-key rotation.
661
-
662
- Pass `onRuntimeDeliveryDiagnostic` to `BundleDrop.init` to export the fast-path
663
- signals to your metrics system. Events contain a bounded counter name, cumulative
664
- process count, timestamp, and optional channel/reason/status metadata; they never
665
- contain access IDs, install IDs, JWS bodies, user properties, or artifact URLs.
666
- `getRuntimeDeliveryDiagnosticCounters()` returns a process-local snapshot. The
667
- counter names are `manifest_hit`, `dynamic_manifest`, `origin_fallback`,
668
- `invalid_signature`, `unknown_key`, `lane_mismatch`,
669
- `generation_regression`, `generation_equivocation`,
670
- `manifest_http_error`, `manifest_network_error`, `manifest_timeout`,
671
- `manifest_too_large`, `manifest_invalid`, `manifest_stream_unavailable`,
672
- `authority_lease_http_error`, `authority_lease_network_error`,
673
- `authority_lease_timeout`, `authority_lease_too_large`,
674
- `authority_lease_invalid`, `authority_lease_invalid_signature`,
675
- `authority_lease_unknown_key`, `authority_lease_expired`,
676
- `authority_lease_origin_mismatch`, and `authority_lease_disabled`.
677
-
678
- Manifest responses are read incrementally and cancelled as soon as they exceed
679
- 1 MiB. A runtime without a readable response stream fails closed to `/ota/resolve`
680
- instead of buffering an unbounded body.
681
-
682
- Managed runtime delivery uses native SHA-256 and ES256 verification. After upgrading to
683
- an SDK release whose `nativeVersion` includes this support (`0.5.0` or newer), run
684
- Pods/prebuild as appropriate and ship a new native binary before enabling runtime
685
- delivery for the project. Bundle Drop's native-version validation will reject a JavaScript/native
686
- adapter mismatch.
687
-
688
- ## Upload an Update
689
-
690
- With the default literal runtime configuration, Expo uploads resolve the app version
691
- through the Expo project and the runtime through `bundle.drop.config.js`. They do not
692
- need `--version`, `--plist-file`, or Gradle-path options:
73
+ From an Expo app with the default runtime configuration:
693
74
 
694
75
  ```bash
695
76
  npx bundle-drop upload ios --channel develop
696
77
  npx bundle-drop upload android --channel develop
697
78
  ```
698
79
 
699
- Bare React Native uploads specify or resolve the app version explicitly:
80
+ From a bare React Native app:
700
81
 
701
82
  ```bash
702
83
  npx bundle-drop upload android --version 1.2.3 --channel develop
703
- npx bundle-drop upload ios --plist-file ios/Info.plist --channel develop
84
+ npx bundle-drop upload ios --plist-file ios/MyApp/Info.plist --channel develop
704
85
  ```
705
86
 
706
- Add `--sourcemap` to produce source maps for error tracking. In CI/CD, pass a
707
- Personal Access Token with `--token <PAT>` instead of using an interactive login.
708
-
709
- To attach multiline Markdown release notes, save them in a file and pass its path
710
- relative to the project directory:
711
-
712
- ```bash
713
- npx bundle-drop upload android --channel develop --release-notes-file ./release-notes.md
714
- ```
87
+ Use the same channel and runtime as the installed Release binary. The CLI prints the uploaded bundle's identity and archive size. For managed publishing, start a rollout in the dashboard to make the upload eligible. With the `on-next-launch` policy above, open the app to download the update, then cold launch it again after the download finishes to verify your change. [Upload options](https://bundledrop.app/docs/uploading#upload-options) · [CI/CD with a Personal Access Token](https://bundledrop.app/docs/ci-cd)
715
88
 
716
- `--release-notes "<text>"` remains available for inline notes. Use only one notes
717
- option per upload. Notes longer than 2,000 characters are truncated with a
718
- warning. After a successful upload, the CLI prints the bundle identity, ZIP size,
719
- source-map and retained-artifact status, bundling/packaging and upload timings,
720
- and a project dashboard link for the exact production or staging API. Custom
721
- servers show the dashboard as unavailable; the CLI has no verified dashboard
722
- origin for them.
723
- The summary confirms the upload; channel publishing and rollout still control
724
- delivery.
89
+ ## Release controls and rollback
725
90
 
726
- ## Update Policies
91
+ - **Runtime compatibility.** Keep a platform's configured `runtimeVersion` for compatible JavaScript and asset changes. For native code, dependency, permission, or configuration changes, update that platform's compatibility boundary and ship a new store binary. [Runtime versions](https://bundledrop.app/docs/runtime-version)
92
+ - **Native fingerprinting (Beta).** Opt in to derive runtime identity from native inputs. Use a matching SDK and dependency lock for the native build and its OTA uploads. [Native fingerprinting guide](https://bundledrop.app/docs/native-fingerprinting) · [Scheme 1 contract](https://github.com/GFean/react-native-bundle-drop/blob/main/docs/native-fingerprint.md)
93
+ - **Staged rollouts.** Enable managed publishing per channel to control eligibility by percentage and user properties. Pausing or narrowing a rollout stops new offers to excluded installations. When the SDK can identify a healthy running bundle as newer than the eligible release on the same channel and runtime, it keeps that bundle and returns `NOOP` with reason `CURRENT_BUNDLE_NEWER`. [Managed publishing](https://bundledrop.app/docs/managed-publishing) · [Staged rollouts](https://bundledrop.app/docs/staged-rollouts) · [Targeting](https://bundledrop.app/docs/targeted-rollout-properties)
94
+ - **Verified patch downloads.** Where a patch is available, the SDK reconstructs and verifies the complete target before staging it. A full bundle is available as a fallback where the resolve decision permits it. [Delivery guide](https://bundledrop.app/docs/uploading)
95
+ - **Native startup recovery.** Failed launches can quarantine the candidate and recover to a previously verified healthy OTA or the embedded bundle. Apps that define their own readiness boundary can use manual health reporting with `BundleDrop.reportHealthy()`. [Automatic recovery](https://bundledrop.app/docs/automatic-recovery) · [Rollback controls](https://bundledrop.app/docs/rollback)
727
96
 
728
- `policy` controls what happens after Bundle Drop hydrates its local state on startup:
97
+ ## Update policies and React UI
729
98
 
730
99
  | Policy | Behavior |
731
100
  | --- | --- |
732
- | `manual` | Check only when you call the APIs yourself. Default. |
733
- | `immediate` | Download and apply a new bundle right away. |
734
- | `on-next-launch` | Stage the update now, then apply it on the next cold launch. |
101
+ | `manual` (default) | The app calls the runtime APIs to check, download, and apply. |
102
+ | `on-next-launch` | Download and stage the update. The next cold launch can start it. |
103
+ | `immediate` | Download, apply, and reload as soon as a new compatible update is ready. |
735
104
 
736
- `on-next-launch` is a good default for most apps: users do not see a reload in the
737
- middle of a session, and the update is ready for the next launch.
105
+ Use `checkOnly` to limit ordinary startup activity to a check. Under the manual policy, a normal `downloadUpdate()` stages the bundle and `applyUpdate()` activates it. Confirmed revocations can trigger native safety recovery. [Update policies](https://bundledrop.app/docs/update-policies) · [Runtime APIs](https://bundledrop.app/docs/runtime-apis)
738
106
 
739
- ## Driving Updates Manually
107
+ ### Show an update overlay
740
108
 
741
- For custom update UI, use the `useBundleDrop()` hook. It subscribes to the singleton
742
- runtime and exposes actions plus live state:
109
+ Mount the overlay near the app root. `useBundleDrop().updatePhase` is `idle`, `checking`, `downloading`, or `applying`. Downloading includes verification and staging, and applying includes an active rollback. A staged bundle waiting for activation reports `idle` with `pendingApply: true`. Use `status` for display text and `isBusy` to disable controls while an operation runs.
743
110
 
744
111
  ```tsx
745
- import { Button } from 'react-native';
112
+ import { ActivityIndicator, Modal, View } from 'react-native';
746
113
  import { useBundleDrop } from '@gfean/react-native-bundle-drop';
747
114
 
748
- function UpdateBanner() {
749
- const { checkLatest, downloadUpdate, applyUpdate, pendingApply, isBusy } =
750
- useBundleDrop();
751
-
752
- if (pendingApply) {
753
- return <Button title="Restart to update" onPress={applyUpdate} />;
754
- }
115
+ function UpdateOverlay() {
116
+ const { updatePhase } = useBundleDrop();
117
+ const visible = updatePhase === 'downloading' || updatePhase === 'applying';
755
118
 
756
119
  return (
757
- <Button
758
- title="Check for updates"
759
- disabled={isBusy}
760
- onPress={async () => {
761
- await checkLatest();
762
- await downloadUpdate();
763
- }}
764
- />
120
+ <Modal transparent visible={visible} onRequestClose={() => {}}>
121
+ <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
122
+ <ActivityIndicator accessibilityLabel="Updating app" />
123
+ </View>
124
+ </Modal>
765
125
  );
766
126
  }
767
127
  ```
768
128
 
769
- The same actions are available as standalone functions (`checkForUpdate`,
770
- `downloadUpdate`, `applyUpdate`, `setChannel`, `reportHealthy`, and others) for use
771
- outside React.
772
-
773
- With `policy: 'manual'`, an ordinary server `ROLLBACK` returned by
774
- `downloadUpdate()` stages a persisted rollback intent without restarting. Its
775
- result includes `status: 'rollback', pendingApply: true`; the hook and
776
- `getUpdateState()` also report `pendingApply`. Call `applyUpdate()` to activate it.
777
- This changes the previous behavior, which rolled back during download itself.
778
- An ordinary startup check does not activate that rollback.
779
-
780
- Before applying, Bundle Drop refreshes the decision and checks that the channel,
781
- runtime and current bundle still match the staged intent. A changed decision or
782
- selection returns `status: 'blocked', reason: 'ROLLBACK_REVALIDATION_FAILED'`;
783
- check/download again. If authority is unavailable, apply is blocked and the intent
784
- remains retryable. A new successful download/staging request replaces the intent.
785
- The intent does not pin a fallback bundle: at explicit apply, native recovery
786
- selects and validates a proven previous bundle or falls back to embedded. Missing,
787
- tampered, incompatible, quarantined and locally known-revoked fallbacks are excluded.
788
-
789
- Safety recovery remains distinct. The existing `CURRENT_REVOKED_NO_COMPATIBLE_TARGET`,
790
- `CURRENT_REVOKED_NO_SAFE_TARGET` and `CURRENT_REVOKED_ORIGIN_UNAVAILABLE` decisions
791
- retain authoritative embedded recovery, including during download or startup
792
- checking. Native crash recovery, runtime compatibility enforcement and persisted
793
- revocation checks are unchanged. `NOOP` (including no published bundle) does not
794
- create a rollback intent. The current backend's no-target revocation decisions
795
- are safety cases; they are not ordinary manual rollback requests.
796
-
797
- ## Targeted Rollouts
798
-
799
- Attach user properties to target specific cohorts when you stage a release:
129
+ See the [`useBundleDrop()` reference](https://bundledrop.app/docs/use-bundle-drop) for update actions, installed bundle metadata, and manual controls.
800
130
 
801
- ```ts
802
- import { setUserProperty } from '@gfean/react-native-bundle-drop';
131
+ ## Observability and OTA source maps
803
132
 
804
- await setUserProperty('plan', 'pro');
805
- await setUserProperty('age', 33);
806
- await setUserProperty('beta', true);
807
- ```
133
+ For symbolicated OTA crashes, generate a source map at upload time and retain the matching bundle and result JSON. This example uses a bare Android project:
808
134
 
809
- Property values must be strings, finite numbers, or booleans. Keys are trimmed and
810
- must be non-empty, 128 characters or fewer, and cannot start with `$`, contain `.`,
811
- contain a null byte, or use reserved prototype names.
135
+ ```bash
136
+ npx bundle-drop upload android --version 1.2.3 --channel develop \
137
+ --sourcemap --artifact-dir ./build/bundledrop
138
+ ```
812
139
 
813
- ## Hybrid OTA Delivery
140
+ Read the uploaded hash from `bundle-drop-result.json`. In the running app, use `getObservabilityContext()` inside your error-tracker setup to read the active bundle:
814
141
 
815
- Bundle Drop installs complete, immutable bundle folders, each identified by a
816
- canonical `bundleHash` for the reconstructed file tree. Patch transport is a download
817
- optimization: the SDK reconstructs the complete target folder, validates the
818
- manifest, verifies file hashes and sizes, and only then promotes the bundle.
142
+ ```ts
143
+ import { getObservabilityContext } from '@gfean/react-native-bundle-drop';
819
144
 
820
- - The SDK supports `asset-only-v1` patch sets and advertises `xdelta3-vcdiff` when
821
- native xdelta support passes its probe.
822
- - If patch transport is unavailable or fails, the SDK falls back to the signed
823
- full ZIP.
824
- - For unmanaged delivery, a patch ZIP HTTP 401/403 permits one attempt of the
825
- full ZIP explicitly supplied by the resolve decision for that same target.
826
- The SDK does not discover another URL or switch targets. A missing fallback,
827
- denied full ZIP, or failed verification fails without activation. Resolve/API
828
- authorization denials and separate manifest/asset download denials do not
829
- enter this exception. Managed delivery retains its bounded authorization
830
- refresh and signed-identity checks described above.
831
- - Rollback remains a local pointer switch between verified bundle hashes.
145
+ const { source, dist, tags } = await getObservabilityContext();
146
+ ```
832
147
 
833
- The production manifest contract is `manifestVersion: 1`. `jsBundleHash` is retained
834
- as metadata only.
148
+ Attach `tags` to crash reports. For Sentry, use the same `release` and `dist` on runtime events and during the source-map upload. For a running OTA, `dist` is its bundle hash. For the embedded bundle, `source` and `dist` are both `embedded`. [Sentry, Bugsnag, and Datadog setup](https://bundledrop.app/docs/observability) · [Sentry with Hermes](https://bundledrop.app/docs/observability#sentry-and-hermes-ota-builds)
835
149
 
836
- ## Observability
150
+ For delivery metrics, pass `onRuntimeDeliveryDiagnostic` to `BundleDrop.init()`. It reports process-local counters such as `manifest_hit` and `origin_fallback`, with bounded diagnostic details. Read a snapshot with `getRuntimeDeliveryDiagnosticCounters()`. [Diagnostic event names](https://github.com/GFean/react-native-bundle-drop/blob/main/src/runtime-delivery/diagnostics.ts)
837
151
 
838
- Every bundle has a unique hash, and `bundle-drop upload --sourcemap` produces source
839
- maps so stack traces remain attributable across updates. Use
840
- `getObservabilityContext()` to tag error reports with the running bundle:
152
+ ## Bundle Drop Sight
841
153
 
842
- ```ts
843
- import { getObservabilityContext } from '@gfean/react-native-bundle-drop';
154
+ Analyze production JavaScript bundles for Expo or bare React Native. Inspect which files and packages take space, compare the working tree with a Git baseline, and review emitted assets. Sight runs locally in your browser and works without a Bundle Drop account.
844
155
 
845
- const context = await getObservabilityContext();
156
+ ```bash
157
+ npx bundle-drop sight --platform android
158
+ npx bundle-drop sight --compare main --platform android
846
159
  ```
847
160
 
848
- This works with Sentry, Bugsnag, Datadog, and other error trackers. See the
849
- [observability guide](https://bundledrop.app/docs/observability). Apps on
850
- `@sentry/react-native` 7.8.x that combine Sentry's Metro wrapper with Hermes should
851
- follow the guide's
852
- [Sentry/Hermes OTA setup](https://bundledrop.app/docs/observability#sentry-and-hermes-ota-builds)
853
- to keep content-derived Debug IDs from inflating binary patches.
161
+ Sight uses source maps for attribution. When the project has the required runtime identity and compiler, it also measures the full Bundle Drop OTA archive. [Sight CLI and comparison guide](https://bundledrop.app/docs/react-native-bundle-analysis) · [Analyze a bundle and source map without the CLI](https://bundledrop.app/docs/react-native-bundle-analysis-without-cli)
854
162
 
855
- ## API Reference
163
+ ## Existing apps and advanced setup
856
164
 
857
- Import the runtime API from `@gfean/react-native-bundle-drop`.
165
+ - **Moving from CodePush or App Center?** Follow the migration checklist for replacing native startup integration, setting up channels, and shipping the first Bundle Drop binary. [CodePush migration](https://bundledrop.app/docs/migrate-from-codepush)
166
+ - **Moving from EAS Update?** An active `expo-updates` integration and Bundle Drop both need native startup ownership. Review the changes from `npx bundle-drop init --project-type expo --migrate-expo-updates` and ship the replacement binary. [Expo migration and build options](https://bundledrop.app/docs/expo)
167
+ - **Using managed runtime delivery?** Setup writes the trust lockfile. Run `npx bundle-drop sync` after a key or route change and use `downloadUpdate()` or the hook's bundle-list install flow for authorized artifacts. The SDK uses signed manifests when it can resolve locally and falls back to the origin for dynamic or unavailable lanes. [CLI reference](https://bundledrop.app/docs/cli) · [Runtime APIs](https://bundledrop.app/docs/runtime-apis)
858
168
 
859
- **Runtime controller**
860
-
861
- | Export | Description |
862
- | --- | --- |
863
- | `BundleDrop.init(options)` | Initialize the runtime for the app process. |
864
- | `BundleDrop.setChannel(name)` / `setChannel` | Change the active channel for singleton actions. |
865
- | `BundleDrop.getChannelName()` / `getChannelName` | Read the active channel. |
866
- | `BundleDrop.reportHealthy()` / `reportHealthy` | In manual health mode, ask native recovery to mark the exact running OTA attempt healthy. |
867
-
868
- **`BundleDrop.init(options)`**
869
-
870
- | Option | Type | Default | Description |
871
- | --- | --- | --- | --- |
872
- | `environment` | `string` | Required | App environment shown in analytics, such as `production`, `staging`, or `development`. |
873
- | `enabled` | `boolean` | `true` | When `false`, the SDK stays configured but does not check, download, or apply. |
874
- | `channelName` | `string` | Config `defaultChannel` (`develop`) | Initial OTA channel for this process. |
875
- | `policy` | `'manual' \| 'immediate' \| 'on-next-launch'` | `'manual'` | Startup behavior after hydration. |
876
- | `checkOnly` | `boolean` | `false` | Startup resolves updates without downloading or applying them. |
877
- | `onStatusUpdate` | `(status: string) => void` | — | Listener for human-readable status messages. |
878
- | `onRuntimeDeliveryDiagnostic` | `(event: RuntimeDeliveryDiagnosticEvent) => void` | — | Listener for bounded runtime-delivery counter events suitable for metrics export. |
879
-
880
- **Update actions** — `checkForUpdate`, `downloadUpdate`, `installBundle`,
881
- `applyUpdate`, `getUpdateState`, `getInstalledBundleInfo`, `getAvailableBundles`,
882
- `getAvailableChannels`.
883
-
884
- **React** — `useBundleDrop()` returns live state (`status`, `isEnabled`, `isBusy`,
885
- `channelName`, `installedInfo`, `pendingApply`, `hasBundle`, `availableChannels`)
886
- plus update actions.
887
-
888
- **User properties** — `setUserProperty`, `removeUserProperty`, `getUserProperties`,
889
- `getCurrentUserProperties`, `resetUserProperties`.
890
-
891
- **Errors** — `BundleDropError`, `isBundleDropError`.
892
-
893
- **Runtime delivery diagnostics** — `getRuntimeDeliveryDiagnosticCounters` returns
894
- the current process-local counter snapshot.
895
-
896
- **Metro** — import `withBundleDropExpo` for Expo or `withBundleDrop` for bare React
897
- Native from `@gfean/react-native-bundle-drop/metro` when configuring Metro manually.
898
-
899
- **CLI** (`npx bundle-drop <command>`) — `login`, `logout`, `whoami`, `init`, `sync`,
900
- `doctor`, `eas-receipt <ios|android>`, and `upload <ios|android>`.
901
-
902
- ## Good to Know
903
-
904
- - **OTA covers JavaScript and assets, not native code.** Native modules, native
905
- dependency upgrades, permissions, native configuration, and React Native upgrades
906
- require a new store binary.
907
- - **Follow store policies.** Use OTA delivery for changes that remain within Apple
908
- and Google requirements and the purpose of the reviewed app.
909
- - **Compatibility checks are deliberate.** A device does not receive an update
910
- built for a different app or runtime version.
911
- - **Release builds run installed OTAs.** Expo Go, Debug builds, and development
912
- clients continue to use their development JavaScript source.
913
- - **Bundle Drop complements crash reporting.** It provides release identity and
914
- source-map support; it does not replace an error tracker.
915
-
916
- ## Docs and Links
917
-
918
- - Website: [bundledrop.app](https://bundledrop.app)
919
- - Docs: [bundledrop.app/docs](https://bundledrop.app/docs)
920
- - Dashboard: [developer.bundledrop.app](https://developer.bundledrop.app)
921
- - Migrating from CodePush: [bundledrop.app/codepush-alternative](https://bundledrop.app/codepush-alternative)
922
- - Issues: [github.com/GFean/react-native-bundle-drop/issues](https://github.com/GFean/react-native-bundle-drop/issues)
923
- - Security: [SECURITY.md](SECURITY.md)
924
- - Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
169
+ Found an issue? [Open a GitHub issue](https://github.com/GFean/react-native-bundle-drop/issues). Report security issues through the [security policy](https://github.com/GFean/react-native-bundle-drop/blob/main/SECURITY.md). See [Contributing](https://github.com/GFean/react-native-bundle-drop/blob/main/CONTRIBUTING.md) for local development and verification.
925
170
 
926
171
  ## License
927
172