@gfean/react-native-bundle-drop 0.2.2 → 0.3.3
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/BundleDrop.podspec +2 -1
- package/LICENSE +15 -0
- package/README.md +122 -238
- package/lib/CLI/cli.d.ts +2 -1
- package/lib/CLI/cli.js +154 -131
- package/lib/CLI/scripts/init-config.js +12 -5
- package/lib/CLI/scripts/init-native-config.d.ts +16 -0
- package/lib/CLI/scripts/init-native-config.js +28 -9
- package/lib/CLI/scripts/login-cli.d.ts +71 -0
- package/lib/CLI/scripts/login-cli.js +24 -13
- package/lib/CLI/scripts/post-init.js +9 -3
- package/lib/CLI/scripts/upload-cli.js +14 -7
- package/lib/api/types.d.ts +29 -0
- package/lib/index.d.ts +16 -4
- package/lib/index.js +25 -15
- package/lib/manager/downloadAndInstall.d.ts +2 -0
- package/lib/manager/reporting.js +3 -0
- package/lib/manager/updateCheck.d.ts +13 -0
- package/lib/manager/updateCheck.js +6 -0
- package/lib/manager/updateState.d.ts +2 -0
- package/lib/manager/updateState.js +10 -4
- package/lib/runtime/initState.d.ts +48 -0
- package/lib/runtime/initState.js +131 -0
- package/lib/runtime/service.d.ts +111 -0
- package/lib/runtime/service.js +537 -0
- package/lib/scripts/bundle.d.ts +13 -1
- package/lib/scripts/bundle.js +126 -115
- package/lib/scripts/download-bundle.d.ts +4 -1
- package/lib/scripts/download-bundle.js +41 -33
- package/lib/scripts/upload-bundle.d.ts +7 -1
- package/lib/scripts/upload-bundle.js +183 -175
- package/lib/useBundleDrop.d.ts +19 -9
- package/lib/useBundleDrop.js +26 -172
- package/package.json +59 -8
- package/CLIENT_README.md +0 -381
- package/lib/manager/initUpdateManager.d.ts +0 -10
- package/lib/manager/initUpdateManager.js +0 -137
package/BundleDrop.podspec
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
require "json"
|
|
2
2
|
|
|
3
3
|
package = JSON.parse(File.read(File.join(__dir__, "package.json")))
|
|
4
|
+
native_version = package["nativeVersion"] || package["version"]
|
|
4
5
|
|
|
5
6
|
Pod::Spec.new do |s|
|
|
6
7
|
s.name = "BundleDrop"
|
|
7
|
-
s.version =
|
|
8
|
+
s.version = native_version
|
|
8
9
|
s.summary = package["description"]
|
|
9
10
|
s.homepage = package["homepage"]
|
|
10
11
|
s.license = package["license"]
|
package/LICENSE
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 GFean
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and/or distribute this software for any
|
|
6
|
+
purpose with or without fee is hereby granted, provided that the above
|
|
7
|
+
copyright notice and this permission notice appear in all copies.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
|
|
10
|
+
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
11
|
+
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
12
|
+
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
|
13
|
+
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
|
|
14
|
+
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
|
15
|
+
PERFORMANCE OF THIS SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,255 +1,139 @@
|
|
|
1
|
-
#
|
|
1
|
+
# BundleDrop
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@gfean/react-native-bundle-drop)
|
|
4
|
+
[](#license)
|
|
5
|
+
[](https://bundledrop.app)
|
|
6
|
+
[](https://bundledrop.app/docs)
|
|
7
|
+
[](https://developer.bundledrop.app)
|
|
8
|
+
|
|
9
|
+
Deploy React Native updates instantly — skip App Store and Play Store delays entirely.
|
|
10
|
+
|
|
11
|
+
Drop-in OTA solution for bare React Native apps.
|
|
12
|
+
|
|
13
|
+
[Website](https://bundledrop.app) • [Docs](https://bundledrop.app/docs) • [Dashboard](https://developer.bundledrop.app)
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Why BundleDrop?
|
|
18
|
+
|
|
19
|
+
Shipping a small fix should not require a full mobile release.
|
|
20
|
+
|
|
21
|
+
BundleDrop lets you ship updates instantly, directly to your users:
|
|
22
|
+
- push JavaScript updates instantly
|
|
23
|
+
- roll out changes gradually
|
|
24
|
+
- target specific channels or cohorts
|
|
25
|
+
- rollback safely when needed
|
|
26
|
+
- manage releases from a dedicated dashboard
|
|
27
|
+
|
|
28
|
+
Built for production React Native apps.
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## What You Can Do
|
|
33
|
+
|
|
34
|
+
- ship production hotfixes in seconds
|
|
35
|
+
- release to `General`, `Beta`, or custom channels
|
|
36
|
+
- target users with dynamic properties
|
|
37
|
+
- control when updates are applied
|
|
38
|
+
- integrate with CI/CD pipelines
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Installation
|
|
4
43
|
|
|
5
|
-
## Install
|
|
6
44
|
```bash
|
|
7
|
-
|
|
8
|
-
cd ios && pod install && cd ..
|
|
45
|
+
npm install @gfean/react-native-bundle-drop
|
|
9
46
|
```
|
|
10
47
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
```js
|
|
14
|
-
// metro.config.js
|
|
15
|
-
const path = require('path');
|
|
16
|
-
|
|
17
|
-
module.exports = {
|
|
18
|
-
resolver: {
|
|
19
|
-
extraNodeModules: {
|
|
20
|
-
// Allows packages to do: require('bundle-drop-config')
|
|
21
|
-
'bundle-drop-config': path.resolve(__dirname, 'bundle.drop.config.js'),
|
|
22
|
-
},
|
|
23
|
-
},
|
|
24
|
-
};
|
|
48
|
+
```bash
|
|
49
|
+
cd ios && pod install
|
|
25
50
|
```
|
|
26
51
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
org: { slug: 'your-org-slug' },
|
|
33
|
-
project: {
|
|
34
|
-
name: 'Your App Name',
|
|
35
|
-
slug: 'your-app-slug',
|
|
36
|
-
apiKey: 'optional-api-key', // project-scoped; auto-filled by CLI init/login
|
|
37
|
-
},
|
|
38
|
-
debugLocal: true, // optional: force localhost (10.0.2.2 on Android, localhost on iOS)
|
|
39
|
-
};
|
|
40
|
-
```
|
|
41
|
-
- Login token stored at `~/.bundle-drop/auth.json` (use CLI `bundle-drop login`).
|
|
42
|
-
- The CLI will fetch a project-scoped `apiKey` from `GET /projects/:projectSlug/credentials` using your JWT and write it into `bundle.drop.config.js`. If you have multiple projects, the CLI prompts you to select the project before fetching credentials.
|
|
43
|
-
|
|
44
|
-
## Runtime APIs (app code)
|
|
45
|
-
- `checkForUpdate(channelName?, onStatusUpdate?)`: resolve-only metadata check (no download). Uses `POST /projects/:projectSlug/ota/resolve` and can return `NOOP`, `INSTALL`, or `ROLLBACK` (plus `NO_COMPATIBLE_BUNDLE` details).
|
|
46
|
-
- `downloadUpdate(options?, onStatusUpdate?)`: resolves (unless `resolvedTarget` is provided), downloads, and stages the update (sets `pendingApply: true`). Returns `{ status: 'staged' | 'upToDate' | 'rollback' | 'incompatible' }`.
|
|
47
|
-
- `applyUpdate(onStatusUpdate?)`: apply a staged update now (restarts the RN bridge).
|
|
48
|
-
- `getUpdateState()`: returns `{ hasBundle, info, pendingApply }` from local metadata.
|
|
49
|
-
- `initUpdateManager({ channelName, policy, onStatusUpdate, checkOnly })`: startup helper
|
|
50
|
-
- `policy: 'manual' | 'immediate' | 'on-next-launch'`
|
|
51
|
-
- `immediate`: download and stage, then apply now (reload). If a staged update is pending, applies it immediately.
|
|
52
|
-
- `on-next-launch`: download and stage; app will pick it up on the next launch (pending flag remains until applied).
|
|
53
|
-
- `manual`: no auto download/apply (resolve still runs for status and rollback decisions).
|
|
54
|
-
- On launch it reconciles pending state, runs rollback guardrails, auto-commits the active bundle, then resolves once. If `ROLLBACK` is returned it switches to `previous.json` (or native fallback) and restarts.
|
|
55
|
-
- `useBundleDrop` hook (optional helper): returns status, busy flag, installed info, pending state, and actions (`checkLatest`, `downloadUpdate`, `applyUpdate`, `fetchAvailableChannels`). Action calls return structured results plus the status string they set.
|
|
56
|
-
- User property APIs (for targeted rollout):
|
|
57
|
-
- `setUserProperty(value: string)`: add a user property (trimmed, de-duplicated).
|
|
58
|
-
- `setUserPropery(value: string)`: backward-compatible alias of `setUserProperty`.
|
|
59
|
-
- `getUserProperties()` and `getCurrentUserProperties()`: read all saved properties.
|
|
60
|
-
- `removeUserProperty(value: string)`: remove one property.
|
|
61
|
-
- `resetUserProperties()`: clear all properties.
|
|
62
|
-
|
|
63
|
-
Android extras:
|
|
64
|
-
- Asset resolver patches (`injectBundleDropImageResolver`, `patchImageRenderToForceResolve`) are applied on module load so images referenced directly still resolve after OTA.
|
|
65
|
-
- Manifest is built at bundle time and merged with a runtime manifest built during unzip to cover filename-only lookups.
|
|
66
|
-
|
|
67
|
-
## Config loading
|
|
68
|
-
- `src/loadConfig.ts` loads `bundle.drop.config.js` (fixed relative path) and honors `debugLocal` to force localhost.
|
|
69
|
-
|
|
70
|
-
## Server API (Public)
|
|
71
|
-
All endpoints are project-scoped and require `x-api-key` (project download API key).
|
|
72
|
-
|
|
73
|
-
### `POST /projects/:projectSlug/ota/resolve`
|
|
74
|
-
Request body:
|
|
75
|
-
```json
|
|
76
|
-
{
|
|
77
|
-
"channelName": "General",
|
|
78
|
-
"platform": "ios|android",
|
|
79
|
-
"runtimeVersion": "3.0.0",
|
|
80
|
-
"currentHash": "abc123",
|
|
81
|
-
"currentUserProperties": ["QA Analyst", "Beta Tester"],
|
|
82
|
-
"previousHash": "prev456",
|
|
83
|
-
"currentBundleVersion": 12,
|
|
84
|
-
"installId": "install-id-string"
|
|
85
|
-
}
|
|
86
|
-
```
|
|
87
|
-
Notes:
|
|
88
|
-
- `installId` is generated once per install and stored at `bundle-drop/install-id.txt` (under the platform-specific `bundle-drop` root).
|
|
89
|
-
- `previousHash` is read from `previous.json` when available.
|
|
90
|
-
- `currentUserProperties` is read from local `bundle-drop/user-properties.json` and sent automatically on each resolve.
|
|
91
|
-
|
|
92
|
-
Response shapes:
|
|
93
|
-
```json
|
|
94
|
-
{ "action": "NOOP", "reason": "UP_TO_DATE" }
|
|
95
|
-
```
|
|
96
|
-
```json
|
|
97
|
-
{
|
|
98
|
-
"action": "NOOP",
|
|
99
|
-
"reason": "NO_COMPATIBLE_BUNDLE",
|
|
100
|
-
"requestedRuntimeVersion": "3.0.0",
|
|
101
|
-
"latestRuntimeVersionOnChannel": "3.1.0"
|
|
102
|
-
}
|
|
103
|
-
```
|
|
104
|
-
```json
|
|
105
|
-
{
|
|
106
|
-
"action": "INSTALL",
|
|
107
|
-
"target": {
|
|
108
|
-
"hash": "def789",
|
|
109
|
-
"downloadUrl": "https://signed-url",
|
|
110
|
-
"bundleVersion": 13,
|
|
111
|
-
"version": "optional",
|
|
112
|
-
"runtimeVersion": "optional"
|
|
113
|
-
}
|
|
114
|
-
}
|
|
115
|
-
```
|
|
116
|
-
```json
|
|
117
|
-
{ "action": "ROLLBACK", "reason": "CURRENT_REVOKED_NO_SAFE_TARGET" }
|
|
118
|
-
```
|
|
119
|
-
Notes:
|
|
120
|
-
- `NOOP` reasons: `UP_TO_DATE`, `ROLLOUT_PAUSED`, `ROLLOUT_NOT_ELIGIBLE`, `NO_PUBLISHED_BUNDLE`, `NO_COMPATIBLE_BUNDLE`.
|
|
121
|
-
- `ROLLBACK` reasons are server-defined (for example: `CURRENT_REVOKED_NO_SAFE_TARGET`, `CURRENT_REVOKED_NO_COMPATIBLE_TARGET`).
|
|
122
|
-
Client behavior:
|
|
123
|
-
- `NOOP`: do nothing.
|
|
124
|
-
- `INSTALL`: download `target.downloadUrl`, stage it, then apply per policy.
|
|
125
|
-
- `ROLLBACK`: switch to `previous.json` if present; otherwise clear `current.json` and fall back to the native bundle (no re-download).
|
|
126
|
-
|
|
127
|
-
### `POST /projects/:projectSlug/bundle/:hash/installed`
|
|
128
|
-
Called once the staged bundle is active (after apply on launch). Used for telemetry.
|
|
129
|
-
Payload fields:
|
|
130
|
-
- `channelName`
|
|
131
|
-
- `platform`
|
|
132
|
-
- `installId` (persistent per-install id stored at `bundle-drop/install-id.txt`)
|
|
133
|
-
- `runtimeVersion`
|
|
134
|
-
|
|
135
|
-
### `GET /projects/:projectSlug/channels/public`
|
|
136
|
-
Returns the list of public channel names.
|
|
137
|
-
|
|
138
|
-
## Rollback behavior (default)
|
|
139
|
-
- Bundles are stored by hash under the platform `bundle-drop` root and activated via `current.json`.
|
|
140
|
-
- The previous active bundle is retained in `previous.json` for rollback.
|
|
141
|
-
- A small `state.json` tracks candidate activation, crash window, and commit status.
|
|
142
|
-
- The module auto-commits the active bundle once JS has started (via `initUpdateManager`/`useBundleDrop`).
|
|
143
|
-
- Server-triggered rollback switches the pointer; if no previous OTA bundle exists, it falls back to the native bundle by clearing `current.json`.
|
|
144
|
-
|
|
145
|
-
Optional rollback policy (tuning only):
|
|
146
|
-
```js
|
|
147
|
-
rollback: {
|
|
148
|
-
maxCrashCount: 2,
|
|
149
|
-
crashWindowSec: 300,
|
|
150
|
-
commitTimeoutSec: 300,
|
|
151
|
-
}
|
|
152
|
-
```
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## Quick Start
|
|
55
|
+
|
|
56
|
+
### 1. Connect your project
|
|
153
57
|
|
|
154
|
-
## Bundling & Uploading (CLI)
|
|
155
|
-
- Login once (interactive, stores JWT locally):
|
|
156
|
-
```bash
|
|
157
|
-
npx bundle-drop login
|
|
158
|
-
```
|
|
159
|
-
- If you need to (re)generate config and fetch the project-scoped API key:
|
|
160
|
-
```bash
|
|
161
|
-
npx bundle-drop init
|
|
162
|
-
npx bundle-drop init --token bdp_pat_xxx # alternative: use a PAT instead of login
|
|
163
|
-
```
|
|
164
|
-
- Upload (builds, zips, uploads, cleans up):
|
|
165
|
-
```bash
|
|
166
|
-
npx bundle-drop upload android --version 1.2.3 --channel General
|
|
167
|
-
npx bundle-drop upload ios --plist-file ios/Info.plist --channel General
|
|
168
|
-
```
|
|
169
|
-
Flags:
|
|
170
|
-
- `--version` (ios/android) or `--plist-file` (iOS) or `--buildgradle-path` (Android) to derive version.
|
|
171
|
-
- `--release-notes "<text>"` optional release notes (max 2000 chars).
|
|
172
|
-
- `--token <pat>` use a Personal Access Token instead of `bundle-drop login`. Ideal for CI/CD.
|
|
173
|
-
- `--author <name>` override the author name stored with the bundle (defaults to uploading user's name).
|
|
174
|
-
- `--runtimeVersion <v>` override runtimeVersion from metadata/config.
|
|
175
|
-
|
|
176
|
-
Requirements:
|
|
177
|
-
- `bundle.drop.config.js` with `serverUrl`, `org.slug`, `project.slug`.
|
|
178
|
-
- `project.apiKey` is used by the client for public endpoints (channel listing + OTA resolve).
|
|
179
|
-
- Authentication via one of: `--token` flag (PAT), or `~/.bundle-drop/auth.json` from `bundle-drop login`.
|
|
180
|
-
|
|
181
|
-
### CI/CD example
|
|
182
58
|
```bash
|
|
183
|
-
npx bundle-drop
|
|
184
|
-
|
|
185
|
-
--channel General \
|
|
186
|
-
--token $BUNDLE_DROP_PAT \
|
|
187
|
-
--author "CI Pipeline"
|
|
59
|
+
npx bundle-drop login
|
|
60
|
+
npx bundle-drop init
|
|
188
61
|
```
|
|
189
62
|
|
|
190
|
-
|
|
63
|
+
### 2. Bootstrap BundleDrop in your app
|
|
64
|
+
|
|
191
65
|
```ts
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
}
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
checkLatest,
|
|
208
|
-
downloadUpdate,
|
|
209
|
-
applyUpdate,
|
|
210
|
-
} = useBundleDrop({ channelName: 'General' });
|
|
211
|
-
|
|
212
|
-
// downloadUpdate() will stage the bundle (applies on next launch or when you call applyUpdate()).
|
|
66
|
+
import { BundleDrop } from '@gfean/react-native-bundle-drop';
|
|
67
|
+
|
|
68
|
+
BundleDrop.init({
|
|
69
|
+
enabled: !__DEV__,
|
|
70
|
+
environment: __DEV__ ? 'STAG' : 'PROD',
|
|
71
|
+
policy: 'on-next-launch',
|
|
72
|
+
channelName: 'General',
|
|
73
|
+
});
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### 3. Ship an update
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
npx bundle-drop upload android --version 1.2.3 --channel General
|
|
80
|
+
npx bundle-drop upload ios --plist-file ios/Info.plist --channel General
|
|
213
81
|
```
|
|
214
82
|
|
|
215
|
-
|
|
83
|
+
Use `--token` in CI/CD pipelines.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## Update Policies
|
|
88
|
+
|
|
89
|
+
Choose how updates are applied:
|
|
90
|
+
|
|
91
|
+
- `manual`: check only, no automatic apply
|
|
92
|
+
- `immediate`: download and apply right away
|
|
93
|
+
- `on-next-launch`: stage now, apply on next launch
|
|
94
|
+
|
|
95
|
+
`on-next-launch` is the safest default for most apps.
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## Why Not App Store Updates?
|
|
100
|
+
|
|
101
|
+
App Store and Play Store releases are slow and heavyweight.
|
|
102
|
+
|
|
103
|
+
BundleDrop gives you instant updates with full control without waiting for review.
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## Targeted Rollouts
|
|
108
|
+
|
|
109
|
+
Use user properties to target specific cohorts:
|
|
110
|
+
|
|
216
111
|
```ts
|
|
217
|
-
import {
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
removeUserProperty,
|
|
221
|
-
resetUserProperties,
|
|
222
|
-
} from '@gfean/react-native-bundle-drop';
|
|
223
|
-
|
|
224
|
-
await setUserProperty('QA Analyst');
|
|
225
|
-
await setUserProperty('Beta Tester');
|
|
226
|
-
await setUserProperty('QA Analyst'); // duplicate ignored
|
|
227
|
-
|
|
228
|
-
const props = await getUserProperties(); // ['QA Analyst', 'Beta Tester']
|
|
229
|
-
await removeUserProperty('Beta Tester');
|
|
230
|
-
await resetUserProperties();
|
|
112
|
+
import { setUserProperty } from '@gfean/react-native-bundle-drop';
|
|
113
|
+
|
|
114
|
+
await setUserProperty('beta');
|
|
231
115
|
```
|
|
232
116
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
-
|
|
249
|
-
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## Docs
|
|
120
|
+
|
|
121
|
+
Full documentation:
|
|
122
|
+
|
|
123
|
+
- Website: [bundledrop.app](https://bundledrop.app)
|
|
124
|
+
- Docs: [bundledrop.app/docs](https://bundledrop.app/docs)
|
|
125
|
+
- Dashboard: [developer.bundledrop.app](https://developer.bundledrop.app)
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## Notes
|
|
130
|
+
|
|
131
|
+
- Requires a BundleDrop backend and project setup
|
|
132
|
+
- Supports React Native on iOS and Android
|
|
133
|
+
- Best suited for bare React Native apps
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## License
|
|
138
|
+
|
|
139
|
+
ISC
|
package/lib/CLI/cli.d.ts
CHANGED