@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 +74 -829
- package/lib/CLI/scripts/upload-cli.js +8 -0
- package/lib/api/types.d.ts +4 -1
- package/lib/index.d.ts +1 -1
- package/lib/manager/downloadAndInstall.d.ts +2 -0
- package/lib/manager/downloadAndInstall.js +10 -1
- package/lib/manager/updateCheck.js +18 -1
- package/lib/manager/updateState.d.ts +1 -1
- package/lib/manager/updateState.js +2 -1
- package/lib/runtime/service.d.ts +2 -0
- package/lib/runtime/service.js +33 -13
- package/lib/runtime-delivery/localResolver.d.ts +3 -0
- package/lib/runtime-delivery/localResolver.js +11 -0
- package/lib/runtime-delivery/runtimeDelivery.d.ts +4 -0
- package/lib/runtime-delivery/runtimeDelivery.js +3 -1
- package/lib/types.d.ts +2 -0
- package/lib/useBundleDrop.d.ts +3 -0
- package/lib/useBundleDrop.js +1 -0
- package/package.json +8 -24
- package/third_party/expo-fingerprint/scheme-1-contract.json +1 -1
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Bundle Drop
|
|
1
|
+
# Bundle Drop — React Native and Expo OTA updates
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@gfean/react-native-bundle-drop)
|
|
4
4
|
[](https://github.com/GFean/react-native-bundle-drop/actions/workflows/ci.yml)
|
|
@@ -7,921 +7,166 @@
|
|
|
7
7
|
[](https://bundledrop.app/docs)
|
|
8
8
|
[](https://developer.bundledrop.app)
|
|
9
9
|
|
|
10
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
|
|
30
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
351
|
-
|
|
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
|
-
|
|
41
|
+
### 2. Configure your project
|
|
391
42
|
|
|
392
|
-
|
|
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
|
-
|
|
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
|
-
|
|
52
|
+
### 3. Initialize the SDK and build a release
|
|
441
53
|
|
|
442
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
97
|
+
## Update policies and React UI
|
|
729
98
|
|
|
730
99
|
| Policy | Behavior |
|
|
731
100
|
| --- | --- |
|
|
732
|
-
| `manual` |
|
|
733
|
-
| `
|
|
734
|
-
| `
|
|
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
|
-
`
|
|
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
|
-
|
|
107
|
+
### Show an update overlay
|
|
740
108
|
|
|
741
|
-
|
|
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 {
|
|
112
|
+
import { ActivityIndicator, Modal, View } from 'react-native';
|
|
746
113
|
import { useBundleDrop } from '@gfean/react-native-bundle-drop';
|
|
747
114
|
|
|
748
|
-
function
|
|
749
|
-
const {
|
|
750
|
-
|
|
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
|
-
<
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
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
|
-
|
|
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
|
-
|
|
802
|
-
import { setUserProperty } from '@gfean/react-native-bundle-drop';
|
|
131
|
+
## Observability and OTA source maps
|
|
803
132
|
|
|
804
|
-
|
|
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
|
-
|
|
810
|
-
|
|
811
|
-
|
|
135
|
+
```bash
|
|
136
|
+
npx bundle-drop upload android --version 1.2.3 --channel develop \
|
|
137
|
+
--sourcemap --artifact-dir ./build/bundledrop
|
|
138
|
+
```
|
|
812
139
|
|
|
813
|
-
|
|
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
|
-
|
|
816
|
-
|
|
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
|
-
|
|
821
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
156
|
+
```bash
|
|
157
|
+
npx bundle-drop sight --platform android
|
|
158
|
+
npx bundle-drop sight --compare main --platform android
|
|
846
159
|
```
|
|
847
160
|
|
|
848
|
-
|
|
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
|
-
##
|
|
163
|
+
## Existing apps and advanced setup
|
|
856
164
|
|
|
857
|
-
|
|
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
|
-
|
|
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
|
|