@gfean/react-native-bundle-drop 0.3.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.
@@ -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 = package["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,278 +1,139 @@
1
- # React Native Bundle Drop (OTA) — Module Guide
1
+ # BundleDrop
2
2
 
3
- This package powers OTA bundle download/upload and asset resolution for React Native.
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
+ [![license](https://img.shields.io/badge/license-ISC-84cc16)](#license)
5
+ [![website](https://img.shields.io/badge/website-bundledrop.app-2563eb)](https://bundledrop.app)
6
+ [![docs](https://img.shields.io/badge/docs-bundledrop.app%2Fdocs-0f766e)](https://bundledrop.app/docs)
7
+ [![dashboard](https://img.shields.io/badge/dashboard-developer.bundledrop.app-111827)](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
- yarn add @gfean/react-native-bundle-drop
8
- cd ios && pod install && cd ..
45
+ npm install @gfean/react-native-bundle-drop
9
46
  ```
10
47
 
11
- ### Metro config (to resolve bundle.drop.config.js from node_modules)
12
- If Metro cannot resolve `bundle.drop.config.js` from within `node_modules`, add an alias in `metro.config.js`:
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
- ## Prerequisites
28
- - `bundle.drop.config.js` in your app root:
29
- ```js
30
- module.exports = {
31
- serverUrl: 'http://localhost:4000', // or prod URL
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
- - `BundleDrop.init({ environment, enabled?, channelName?, policy?, onStatusUpdate?, checkOnly? })`: required startup entrypoint.
46
- - `environment` is required and should come from your app runtime config (`.env`, schema, build flavor, etc.), not from `bundle.drop.config.js`.
47
- - `enabled` defaults to `true`. Set `enabled: false` to keep BundleDrop configured but fully no-op for the current runtime.
48
- - When `enabled: false`, BundleDrop does not run startup OTA work and public OTA actions return disabled/no-op results while warning once.
49
- - `policy: 'manual' | 'immediate' | 'on-next-launch'`
50
- - `manual`: initialize BundleDrop, hydrate local state, run rollback guardrails, and commit the active bundle, but do not auto-resolve/download/apply.
51
- - `immediate`: after startup checks, download and apply immediately.
52
- - `on-next-launch`: after startup checks, download and stage for the next launch.
53
- - `checkOnly: true` limits startup to a resolve/check and skips download/apply even if policy is not `manual`.
54
- - Same-config double init is a no-op. Different-config re-init throws.
55
- - `BundleDrop.setChannel(channelName)`: change the active runtime channel for subsequent singleton OTA actions.
56
- - `BundleDrop.getChannelName()`: read the current active runtime channel.
57
- - `checkForUpdate(onStatusUpdate?)`: resolve-only metadata check (no download). Uses the channel/environment from `BundleDrop.init(...)` and can return `NOOP`, `INSTALL`, or `ROLLBACK` (plus `NO_COMPATIBLE_BUNDLE` details).
58
- - `downloadUpdate(onStatusUpdate?)`: resolves, downloads, and stages the update (sets `pendingApply: true`). Returns `{ status: 'staged' | 'upToDate' | 'rollback' | 'incompatible' | 'disabled' }`.
59
- - `applyUpdate(onStatusUpdate?)`: apply a staged update now (restarts the RN bridge). Returns `{ status: 'applied' | 'noBundle' | 'alreadyApplied' | 'disabled' }`.
60
- - `getUpdateState()`: returns `{ hasBundle, info, pendingApply }` from local metadata.
61
- - `getAvailableBundles(options?)`: fetch a paginated list of downloadable bundles for a channel.
62
- - `installBundle(hash, downloadUrl, bundleVersion?, version?, runtimeVersion?, onStatusUpdate?)`: manually stage a specific bundle by hash and URL.
63
- - `useBundleDrop()` hook (optional helper): subscriber over the singleton runtime started by `BundleDrop.init(...)`. Returns `channelName`, `setChannel`, `isEnabled`, status, busy flag, installed info, pending state, and actions (`checkLatest`, `downloadUpdate`, `applyUpdate`, `fetchAvailableChannels`, `fetchBundles`, `installBundle`). If init is missing, it warns once and exposes a disabled no-op snapshot instead of throwing.
64
- - User property APIs (for targeted rollout):
65
- - `setUserProperty(value: string)`: add a user property (trimmed, de-duplicated).
66
- - `setUserPropery(value: string)`: backward-compatible alias of `setUserProperty`.
67
- - `getUserProperties()` and `getCurrentUserProperties()`: read all saved properties.
68
- - `removeUserProperty(value: string)`: remove one property.
69
- - `resetUserProperties()`: clear all properties.
70
-
71
- Android extras:
72
- - Asset resolver patches (`injectBundleDropImageResolver`, `patchImageRenderToForceResolve`) are applied on module load so images referenced directly still resolve after OTA.
73
- - Manifest is built at bundle time and merged with a runtime manifest built during unzip to cover filename-only lookups.
74
-
75
- ## Config loading
76
- - `src/loadConfig.ts` loads `bundle.drop.config.js` (fixed relative path) and honors `debugLocal` to force localhost.
77
-
78
- ## Server API (Public)
79
- All endpoints are project-scoped and require `x-api-key` (project download API key).
80
-
81
- ### `POST /projects/:projectSlug/ota/resolve`
82
- Request body:
83
- ```json
84
- {
85
- "channelName": "General",
86
- "platform": "ios|android",
87
- "runtimeVersion": "3.0.0",
88
- "environment": "production",
89
- "currentHash": "abc123",
90
- "currentUserProperties": { "cohort": "beta" },
91
- "previousHash": "prev456",
92
- "currentBundleVersion": 12,
93
- "installId": "install-id-string"
94
- }
95
- ```
96
- Notes:
97
- - `installId` is generated once per install and stored at `bundle-drop/install-id.txt` (under the platform-specific `bundle-drop` root).
98
- - `previousHash` is read from `previous.json` when available.
99
- - `currentUserProperties` is read from local `bundle-drop/user-properties.json` and sent automatically on each resolve.
100
- - `environment` is read from `BundleDrop.init(...)` and sent automatically on resolve/install telemetry.
101
-
102
- Response shapes:
103
- ```json
104
- { "action": "NOOP", "reason": "UP_TO_DATE" }
105
- ```
106
- ```json
107
- {
108
- "action": "NOOP",
109
- "reason": "NO_COMPATIBLE_BUNDLE",
110
- "requestedRuntimeVersion": "3.0.0",
111
- "latestRuntimeVersionOnChannel": "3.1.0"
112
- }
113
- ```
114
- ```json
115
- {
116
- "action": "INSTALL",
117
- "target": {
118
- "hash": "def789",
119
- "downloadUrl": "https://signed-url",
120
- "bundleVersion": 13,
121
- "version": "optional",
122
- "runtimeVersion": "optional"
123
- }
124
- }
125
- ```
126
- ```json
127
- { "action": "ROLLBACK", "reason": "CURRENT_REVOKED_NO_SAFE_TARGET" }
128
- ```
129
- Notes:
130
- - `NOOP` reasons: `UP_TO_DATE`, `ROLLOUT_PAUSED`, `ROLLOUT_NOT_ELIGIBLE`, `NO_PUBLISHED_BUNDLE`, `NO_COMPATIBLE_BUNDLE`.
131
- - `ROLLBACK` reasons are server-defined (for example: `CURRENT_REVOKED_NO_SAFE_TARGET`, `CURRENT_REVOKED_NO_COMPATIBLE_TARGET`).
132
- Client behavior:
133
- - `NOOP`: do nothing.
134
- - `INSTALL`: download `target.downloadUrl`, stage it, then apply per policy.
135
- - `ROLLBACK`: switch to `previous.json` if present; otherwise clear `current.json` and fall back to the native bundle (no re-download).
136
-
137
- ### `POST /projects/:projectSlug/bundle/:hash/installed`
138
- Called once the staged bundle is active (after apply on launch). Used for telemetry.
139
- Payload fields:
140
- - `channelName`
141
- - `platform`
142
- - `installId` (persistent per-install id stored at `bundle-drop/install-id.txt`)
143
- - `runtimeVersion`
144
- - `environment`
145
-
146
- ### `GET /projects/:projectSlug/channels/public`
147
- Returns the list of public channel names.
148
-
149
- ## Rollback behavior (default)
150
- - Bundles are stored by hash under the platform `bundle-drop` root and activated via `current.json`.
151
- - The previous active bundle is retained in `previous.json` for rollback.
152
- - A small `state.json` tracks candidate activation, crash window, and commit status.
153
- - The module auto-commits the active bundle once JS has started (via `BundleDrop.init(...)`).
154
- - Server-triggered rollback switches the pointer; if no previous OTA bundle exists, it falls back to the native bundle by clearing `current.json`.
155
-
156
- Optional rollback policy (tuning only):
157
- ```js
158
- rollback: {
159
- maxCrashCount: 2,
160
- crashWindowSec: 300,
161
- commitTimeoutSec: 300,
162
- }
163
- ```
52
+ ---
53
+
54
+ ## Quick Start
55
+
56
+ ### 1. Connect your project
164
57
 
165
- ## Bundling & Uploading (CLI)
166
- - Login once (interactive, stores JWT locally):
167
- ```bash
168
- npx bundle-drop login
169
- ```
170
- - If you need to (re)generate config and fetch the project-scoped API key:
171
- ```bash
172
- npx bundle-drop init
173
- npx bundle-drop init --token bdp_pat_xxx # alternative: use a PAT instead of login
174
- ```
175
- - Upload (builds, zips, uploads, cleans up):
176
- ```bash
177
- npx bundle-drop upload android --version 1.2.3 --channel General
178
- npx bundle-drop upload ios --plist-file ios/Info.plist --channel General
179
- ```
180
- Flags:
181
- - `--version` (ios/android) or `--plist-file` (iOS) or `--buildgradle-path` (Android) to derive version.
182
- - `--release-notes "<text>"` optional release notes (max 2000 chars).
183
- - `--token <pat>` use a Personal Access Token instead of `bundle-drop login`. Ideal for CI/CD.
184
- - `--author <name>` override the author name stored with the bundle (defaults to uploading user's name).
185
- - `--runtimeVersion <v>` override runtimeVersion from metadata/config.
186
-
187
- Requirements:
188
- - `bundle.drop.config.js` with `serverUrl`, `org.slug`, `project.slug`.
189
- - `project.apiKey` is used by the client for public endpoints (channel listing + OTA resolve).
190
- - Authentication via one of: `--token` flag (PAT), or `~/.bundle-drop/auth.json` from `bundle-drop login`.
191
-
192
- ### CI/CD example
193
58
  ```bash
194
- npx bundle-drop upload android \
195
- --version 1.2.3 \
196
- --channel General \
197
- --token $BUNDLE_DROP_PAT \
198
- --author "CI Pipeline"
59
+ npx bundle-drop login
60
+ npx bundle-drop init
199
61
  ```
200
62
 
201
- ## Typical usage
63
+ ### 2. Bootstrap BundleDrop in your app
64
+
202
65
  ```ts
203
- // index.js / entry
204
- import '@gfean/react-native-bundle-drop/bootstrap';
205
66
  import { BundleDrop } from '@gfean/react-native-bundle-drop';
206
67
 
207
68
  BundleDrop.init({
208
69
  enabled: !__DEV__,
209
- environment: __DEV__ ? 'development' : 'production',
210
- policy: __DEV__ ? 'manual' : 'on-next-launch',
70
+ environment: __DEV__ ? 'STAG' : 'PROD',
71
+ policy: 'on-next-launch',
211
72
  channelName: 'General',
212
- onStatusUpdate: msg => console.log('[OTA]', msg),
213
73
  });
74
+ ```
75
+
76
+ ### 3. Ship an update
214
77
 
215
- // Manual UI (hook)
216
- const {
217
- channelName,
218
- setChannel,
219
- isEnabled,
220
- status,
221
- isBusy,
222
- installedInfo,
223
- pendingApply,
224
- checkLatest,
225
- downloadUpdate,
226
- applyUpdate,
227
- fetchBundles,
228
- installBundle,
229
- } = useBundleDrop();
230
-
231
- setChannel('Beta');
232
-
233
- // downloadUpdate() will stage the bundle (applies on next launch or when you call applyUpdate()).
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
234
81
  ```
235
82
 
236
- ## Targeted rollout properties
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
+
237
111
  ```ts
238
- import {
239
- setUserProperty,
240
- getUserProperties,
241
- removeUserProperty,
242
- resetUserProperties,
243
- } from '@gfean/react-native-bundle-drop';
244
-
245
- await setUserProperty('QA Analyst');
246
- await setUserProperty('Beta Tester');
247
- await setUserProperty('QA Analyst'); // duplicate ignored
248
-
249
- const props = await getUserProperties(); // ['QA Analyst', 'Beta Tester']
250
- await removeUserProperty('Beta Tester');
251
- await resetUserProperties();
112
+ import { setUserProperty } from '@gfean/react-native-bundle-drop';
113
+
114
+ await setUserProperty('beta');
252
115
  ```
253
116
 
254
- ## CLI (bin)
255
- - `modules/react-native-bundle-drop/src/CLI/cli.ts` provides:
256
- - `bundle-drop login|logout|whoami`
257
- - `bundle-drop init [--token <pat>]`
258
- - `bundle-drop upload <platform> --version <ver> --channel <name> [--plist-file <path>] [--runtimeVersion <v>] [--release-notes "<text>"] [--token <pat>] [--author <name>]`
259
- - Auth via `--token` (PAT) or `~/.bundle-drop/auth.json` (from `bundle-drop login`).
260
-
261
- ## Android localhost note
262
- - When `debugLocal` is true (or env is set), Android uses `http://10.0.2.2:4000`; iOS uses `http://localhost:4000`.
263
-
264
- ## Troubleshooting
265
- - If bundling fails with `EMFILE`, raise file descriptor limit (`ulimit -n 8192`) and retry.
266
- - Ensure `bundle.drop.config.js` has `serverUrl`, `org.slug`, and `project.slug`; otherwise the module falls back to localhost defaults.
267
- - If you want BundleDrop off in Metro/dev, prefer `BundleDrop.init({ enabled: false, ... })` over skipping init entirely. That keeps hook consumers mounted safely while OTA APIs remain no-op.
268
-
269
- ## Maintainer notes (internal structure)
270
- - `src/index.tsx` is a thin barrel for public exports.
271
- - Early side-effects/config live in `src/bootstrap.ts` (loads config, detects platform, patches Android images).
272
- - File system helpers: `src/fs/*` (atomic writes, bundle pointers).
273
- - Rollback/state helpers: `src/manager/rollbackState.ts`.
274
- - Native accessors: `src/native/bundleDropNative.ts`.
275
- - Install flow: `src/install/installFromZip.ts`.
276
- - API client layer: `src/api/*` (axios client + typed endpoints).
277
- - Runtime service/state: `src/runtime/*` (`initState`, `service`).
278
- - Update managers: `src/manager/*` (`updateCheck`, `downloadAndInstall`, `updateState`, `reporting`).
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.js CHANGED
@@ -23,6 +23,9 @@ const logo = chalk_1.default.cyanBright(`
23
23
  |_______/|______.'
24
24
  `) + chalk_1.default.bold.cyanBright(`\n${figures_1.default.star} React Native Bundle Drop CLI ${figures_1.default.star}`);
25
25
  const DEFAULT_SERVER_URL = 'https://api.bundledrop.app';
26
+ const DOCS_CLI_URL = 'https://bundledrop.app/docs/cli';
27
+ const DOCS_UPLOADING_URL = 'https://bundledrop.app/docs/uploading';
28
+ const DOCS_CI_CD_URL = 'https://bundledrop.app/docs/ci-cd';
26
29
  const getTokenPath = () => path_1.default.join(os_1.default.homedir(), '.bundle-drop', 'auth.json');
27
30
  const normalizeServerUrl = (url) => url?.replace(/\/$/, '') || DEFAULT_SERVER_URL;
28
31
  const readStoredAuthData = () => {
@@ -43,7 +46,9 @@ const readStoredAuthData = () => {
43
46
  }
44
47
  };
45
48
  const logInvalidAuthFile = () => {
46
- console.log('❌ Failed to read CLI auth session. Please run `bundle-drop login` again or use --token.');
49
+ console.log('❌ Failed to read CLI auth session. Please run `bundle-drop login` again or use --token.\n' +
50
+ `CLI docs: ${DOCS_CLI_URL}\n` +
51
+ `CI/CD docs: ${DOCS_CI_CD_URL}`);
47
52
  };
48
53
  const buildProgram = () => {
49
54
  const program = new commander_1.Command();
@@ -63,7 +68,9 @@ ${chalk_1.default.bold.cyan('Common Usage:')}
63
68
  ${chalk_1.default.gray('bundle-drop upload ios --plist-file ios/Info.plist --channel General')}
64
69
  ${chalk_1.default.gray('bundle-drop upload android --buildgradle-path android/app/build.gradle --channel General --release-notes "Fixes"')}
65
70
 
66
- ${chalk_1.default.gray('Need help? →')} ${chalk_1.default.underline.gray('https://github.com/GFean/react-native-bundle-drop')}\n`);
71
+ ${chalk_1.default.gray('Docs →')} ${chalk_1.default.underline.gray(DOCS_CLI_URL)}
72
+ ${chalk_1.default.gray('Uploading →')} ${chalk_1.default.underline.gray(DOCS_UPLOADING_URL)}
73
+ ${chalk_1.default.gray('CI/CD →')} ${chalk_1.default.underline.gray(DOCS_CI_CD_URL)}\n`);
67
74
  program
68
75
  .command('upload')
69
76
  .argument('<platform>', chalk_1.default.gray('ios or android'))
@@ -83,6 +90,9 @@ ${chalk_1.default.bold('Examples:')}
83
90
  ${chalk_1.default.gray('bundle-drop upload android --buildgradle-path android/app/build.gradle --channel QA --release-notes "Bug fixes"')}
84
91
  ${chalk_1.default.gray('bundle-drop upload android --version 1.2.3 --channel General --runtimeVersion 3.0.0')}
85
92
  ${chalk_1.default.gray('bundle-drop upload android --version 1.2.3 --channel General --token bdp_pat_xxx')}
93
+
94
+ ${chalk_1.default.gray('Uploading docs →')} ${chalk_1.default.underline.gray(DOCS_UPLOADING_URL)}
95
+ ${chalk_1.default.gray('CI/CD docs →')} ${chalk_1.default.underline.gray(DOCS_CI_CD_URL)}
86
96
  `)
87
97
  .action(upload_cli_1.default);
88
98
  program
@@ -122,7 +132,9 @@ ${chalk_1.default.bold('Examples:')}
122
132
  }
123
133
  const authState = readStoredAuthData();
124
134
  if (!authState.exists) {
125
- console.log('ℹ️ Not logged in. Please run `bundle-drop login` or use --token.');
135
+ console.log('ℹ️ Not logged in. Please run `bundle-drop login` or use --token.\n' +
136
+ `CLI docs: ${DOCS_CLI_URL}\n` +
137
+ `CI/CD docs: ${DOCS_CI_CD_URL}`);
126
138
  return;
127
139
  }
128
140
  if (authState.isInvalid || !authState.data) {
@@ -11,6 +11,8 @@ const chalk_1 = __importDefault(require("chalk"));
11
11
  const fs_extra_1 = __importDefault(require("fs-extra"));
12
12
  const path_1 = __importDefault(require("path"));
13
13
  const prompts_1 = __importDefault(require("prompts"));
14
+ const DOCS_PROJECT_CREATION_URL = 'https://bundledrop.app/docs/project-creation';
15
+ const DOCS_INSTALLATION_URL = 'https://bundledrop.app/docs/installation';
14
16
  function normalizeServerUrl(url) {
15
17
  return url.replace(/\/$/, '');
16
18
  }
@@ -28,7 +30,8 @@ async function fetchProjectCredentials(params) {
28
30
  return res.data || null;
29
31
  }
30
32
  catch (err) {
31
- console.log(chalk_1.default.yellow(`⚠️ Failed to fetch project credentials from ${url}. Please verify login and project access.`));
33
+ console.log(chalk_1.default.yellow(`⚠️ Failed to fetch project credentials from ${url}. Please verify login and project access.\n` +
34
+ `If the project is not set up yet, see ${DOCS_PROJECT_CREATION_URL}`));
32
35
  return null;
33
36
  }
34
37
  }
@@ -55,14 +58,16 @@ function hasExistingBundleDropConfig(startDir = process.cwd()) {
55
58
  async function initConfig(params) {
56
59
  const configPath = getBundleDropConfigPath();
57
60
  if (fs_extra_1.default.existsSync(configPath)) {
58
- console.log(chalk_1.default.yellow(`ℹ️ bundle.drop.config.js already exists at ${configPath}. If this is accidental, delete it and rerun the init/login.`));
61
+ console.log(chalk_1.default.yellow(`ℹ️ bundle.drop.config.js already exists at ${configPath}. If this is accidental, delete it and rerun the init/login.\n` +
62
+ `See ${DOCS_INSTALLATION_URL}`));
59
63
  return;
60
64
  }
61
65
  let orgSlug = '';
62
66
  let project = null;
63
67
  // Org selection
64
68
  if (!params.organizations || params.organizations.length === 0) {
65
- console.log(chalk_1.default.yellow('⚠️ No organizations returned; org slug will be left blank.'));
69
+ console.log(chalk_1.default.yellow(`⚠️ No organizations returned; org slug will be left blank.\n` +
70
+ `Create an organization first: ${DOCS_PROJECT_CREATION_URL}`));
66
71
  }
67
72
  else if (params.organizations.length === 1) {
68
73
  orgSlug = params.organizations[0].slug;
@@ -85,7 +90,8 @@ async function initConfig(params) {
85
90
  }
86
91
  // Project selection
87
92
  if (!params.projects?.length) {
88
- console.log(chalk_1.default.red('⚠️ No projects returned; project values will be left blank.'));
93
+ console.log(chalk_1.default.red(`⚠️ No projects returned; project values will be left blank.\n` +
94
+ `Create a project first: ${DOCS_PROJECT_CREATION_URL}`));
89
95
  }
90
96
  else if (params.projects.length === 1) {
91
97
  project = params.projects[0];
@@ -125,7 +131,8 @@ async function initConfig(params) {
125
131
  apiKey = credentials.downloadApiKey;
126
132
  }
127
133
  else if (!apiKey) {
128
- console.log(chalk_1.default.yellow('⚠️ No project API key returned from /projects/:projectSlug/credentials; config will be created without apiKey.'));
134
+ console.log(chalk_1.default.yellow('⚠️ No project API key returned from /projects/:projectSlug/credentials; config will be created without apiKey.\n' +
135
+ `See ${DOCS_INSTALLATION_URL}`));
129
136
  }
130
137
  }
131
138
  else if (projectSlug && !params.authToken && !apiKey) {
@@ -19,6 +19,9 @@ const chalk_1 = __importDefault(require("chalk"));
19
19
  const fs_extra_1 = __importDefault(require("fs-extra"));
20
20
  const path_1 = __importDefault(require("path"));
21
21
  const prompts_1 = __importDefault(require("prompts"));
22
+ const DOCS_INSTALLATION_URL = 'https://bundledrop.app/docs/installation';
23
+ const DOCS_ANDROID_NATIVE_SETUP_URL = `${DOCS_INSTALLATION_URL}#android-mainapplication`;
24
+ const DOCS_IOS_NATIVE_SETUP_URL = `${DOCS_INSTALLATION_URL}#ios-appdelegate`;
22
25
  function findProjectRoot(startDir) {
23
26
  let dir = path_1.default.resolve(startDir);
24
27
  const MAX_UP = 12;
@@ -226,7 +229,8 @@ function patchAndroidMainApplicationKotlin(filePath) {
226
229
  }
227
230
  else {
228
231
  console.log(chalk_1.default.yellow(` ⚠️ Could not find a suitable insertion point in ${filePath}.\n` +
229
- ` Please add the reactNativeHost + reactHost blocks manually (see CLIENT_README.md).`));
232
+ ` Please add the reactNativeHost + reactHost blocks manually.\n` +
233
+ ` See ${DOCS_ANDROID_NATIVE_SETUP_URL}`));
230
234
  return;
231
235
  }
232
236
  }
@@ -245,7 +249,8 @@ function patchAndroidMainApplicationKotlin(filePath) {
245
249
  }
246
250
  // 4. No recognizable template
247
251
  console.log(chalk_1.default.yellow(` ⚠️ Could not detect a supported MainApplication template in ${filePath}.\n` +
248
- ` Please add the BundleDrop override manually. See CLIENT_README.md section "Native setup (Android)".`));
252
+ ` Please add the BundleDrop override manually.\n` +
253
+ ` See ${DOCS_ANDROID_NATIVE_SETUP_URL}`));
249
254
  }
250
255
  // ---------------------------------------------------------------------------
251
256
  // Android MainApplication.java patcher (older RN versions)
@@ -296,7 +301,8 @@ function patchAndroidMainApplicationJava(filePath) {
296
301
  }
297
302
  }
298
303
  console.log(chalk_1.default.yellow(` ⚠️ Found getJSBundleFile() but could not safely parse its body.\n` +
299
- ` Please replace the method body manually. See CLIENT_README.md section "Native setup (Android)".`));
304
+ ` Please replace the method body manually.\n` +
305
+ ` See ${DOCS_ANDROID_NATIVE_SETUP_URL}`));
300
306
  return;
301
307
  }
302
308
  // 3. Has ReactNativeHost anonymous class — inject getJSBundleFile() inside it
@@ -336,12 +342,14 @@ function patchAndroidMainApplicationJava(filePath) {
336
342
  }
337
343
  }
338
344
  console.log(chalk_1.default.yellow(` ⚠️ Found ReactNativeHost but could not safely parse its anonymous class.\n` +
339
- ` Please add getJSBundleFile() override manually. See CLIENT_README.md section "Native setup (Android)".`));
345
+ ` Please add getJSBundleFile() override manually.\n` +
346
+ ` See ${DOCS_ANDROID_NATIVE_SETUP_URL}`));
340
347
  return;
341
348
  }
342
349
  // 4. No recognizable template
343
350
  console.log(chalk_1.default.yellow(` ⚠️ Could not detect a supported MainApplication template in ${filePath}.\n` +
344
- ` Please add the BundleDrop override manually. See CLIENT_README.md section "Native setup (Android)".`));
351
+ ` Please add the BundleDrop override manually.\n` +
352
+ ` See ${DOCS_ANDROID_NATIVE_SETUP_URL}`));
345
353
  }
346
354
  function patchAndroidMainApplication(filePath) {
347
355
  const ext = path_1.default.extname(filePath);
@@ -354,7 +362,7 @@ function patchAndroidMainApplication(filePath) {
354
362
  }
355
363
  else {
356
364
  console.log(chalk_1.default.yellow(` ⚠️ Unsupported MainApplication file type (${ext}). Please patch manually.\n` +
357
- ` See CLIENT_README.md section "Native setup (Android)".`));
365
+ ` See ${DOCS_ANDROID_NATIVE_SETUP_URL}`));
358
366
  }
359
367
  }
360
368
  // ---------------------------------------------------------------------------
@@ -431,7 +439,7 @@ function patchIosAppDelegateSwift(filePath) {
431
439
  fs_extra_1.default.writeFileSync(filePath, content, 'utf8');
432
440
  console.log(chalk_1.default.yellow(` ⚠️ Could not find bundleURL() override in ${filePath}.\n` +
433
441
  ` Please add manually: Debug → Metro, Release → BundleDropLocator.bundleURL() fallback to main.jsbundle.\n` +
434
- ` See CLIENT_README.md section "Native setup (iOS)".`));
442
+ ` See ${DOCS_IOS_NATIVE_SETUP_URL}`));
435
443
  }
436
444
  function patchIosAppDelegateObjc(filePath) {
437
445
  let content = fs_extra_1.default.readFileSync(filePath, 'utf8');
@@ -471,7 +479,7 @@ function patchIosAppDelegateObjc(filePath) {
471
479
  fs_extra_1.default.writeFileSync(filePath, content, 'utf8');
472
480
  console.log(chalk_1.default.yellow(` ⚠️ Could not find sourceURLForBridge: in ${filePath}.\n` +
473
481
  ` Please locate the method that returns the JS bundle URL and apply the Release OTA fallback.\n` +
474
- ` See CLIENT_README.md section "Native setup (iOS)".`));
482
+ ` See ${DOCS_IOS_NATIVE_SETUP_URL}`));
475
483
  }
476
484
  function patchIosAppDelegate(filePath) {
477
485
  const ext = path_1.default.extname(filePath);
@@ -484,7 +492,7 @@ function patchIosAppDelegate(filePath) {
484
492
  }
485
493
  else {
486
494
  console.log(chalk_1.default.yellow(` ⚠️ Unsupported AppDelegate file type (${ext}). Please patch manually.\n` +
487
- ` See CLIENT_README.md section "Native setup (iOS)".`));
495
+ ` See ${DOCS_IOS_NATIVE_SETUP_URL}`));
488
496
  }
489
497
  }
490
498
  async function initNativeConfig() {
@@ -5,6 +5,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
6
  exports.runPostInitPrompts = runPostInitPrompts;
7
7
  const prompts_1 = __importDefault(require("prompts"));
8
+ const DOCS_INSTALLATION_URL = 'https://bundledrop.app/docs/installation';
9
+ const DOCS_METRO_SETUP_URL = `${DOCS_INSTALLATION_URL}#metro-setup`;
10
+ const DOCS_NATIVE_SETUP_URL = `${DOCS_INSTALLATION_URL}#manual-native-setup`;
8
11
  async function runPostInitPrompts() {
9
12
  // Offer to set up Metro alias for bundle.drop.config.js resolution
10
13
  const metroAnswer = await (0, prompts_1.default)({
@@ -19,7 +22,8 @@ async function runPostInitPrompts() {
19
22
  await require('./init-metro-config').initMetroConfig();
20
23
  }
21
24
  catch (err) {
22
- console.log(`⚠️ Failed to initialize Metro config; please refer to manual setup instructions. (${err?.message || err})`);
25
+ console.log(`⚠️ Failed to initialize Metro config; please refer to manual setup instructions.\n` +
26
+ `See ${DOCS_METRO_SETUP_URL} (${err?.message || err})`);
23
27
  }
24
28
  }
25
29
  // Offer to patch native entrypoints (after Metro prompt finishes)
@@ -33,10 +37,12 @@ async function runPostInitPrompts() {
33
37
  try {
34
38
  //eslint-disable-next-line
35
39
  await require('./init-native-config').initNativeConfig();
36
- console.log('⚠️ Please double-check the native changes in MainApplication/AppDelegate.');
40
+ console.log(`⚠️ Please double-check the native changes in MainApplication/AppDelegate.\n` +
41
+ `See ${DOCS_NATIVE_SETUP_URL}`);
37
42
  }
38
43
  catch (err) {
39
- console.log(`⚠️ Failed to initialize native config; please refer to manual setup instructions. (${err?.message || err})`);
44
+ console.log(`⚠️ Failed to initialize native config; please refer to manual setup instructions.\n` +
45
+ `See ${DOCS_NATIVE_SETUP_URL} (${err?.message || err})`);
40
46
  }
41
47
  }
42
48
  }
@@ -44,6 +44,10 @@ const fs = __importStar(require("fs"));
44
44
  const path = __importStar(require("path"));
45
45
  const plist = __importStar(require("plist"));
46
46
  const ui_1 = require("../utils/ui");
47
+ const DOCS_INSTALLATION_URL = 'https://bundledrop.app/docs/installation';
48
+ const DOCS_UPLOADING_URL = 'https://bundledrop.app/docs/uploading';
49
+ const DOCS_CI_CD_URL = 'https://bundledrop.app/docs/ci-cd';
50
+ const DOCS_RUNTIME_VERSION_URL = 'https://bundledrop.app/docs/runtime-version';
47
51
  const getPackageRoot = () => process.env.BUNDLE_DROP_PACKAGE_ROOT_OVERRIDE || path.resolve(__dirname, '..', '..', '..');
48
52
  async function upload(platform, options) {
49
53
  console.log(); // blank line
@@ -54,7 +58,7 @@ async function upload(platform, options) {
54
58
  const authPath = path.join(require('os').homedir(), '.bundle-drop', 'auth.json');
55
59
  // Validate config
56
60
  if (!fs.existsSync(configPath)) {
57
- ui_1.log.error('❌ bundle.drop.config.js not found in project root');
61
+ ui_1.log.error(`❌ bundle.drop.config.js not found in project root\nSee ${DOCS_INSTALLATION_URL}`);
58
62
  process.exit(1);
59
63
  }
60
64
  //eslint-disable-next-line
@@ -63,14 +67,16 @@ async function upload(platform, options) {
63
67
  const orgSlug = config.org?.slug;
64
68
  const projectSlug = config.project?.slug;
65
69
  if (!serverUrl || !projectSlug || !orgSlug) {
66
- ui_1.log.error('❌ Missing "serverUrl", "org.slug" or "project.slug" in config');
70
+ ui_1.log.error(`❌ Missing "serverUrl", "org.slug" or "project.slug" in config\nSee ${DOCS_INSTALLATION_URL}`);
67
71
  process.exit(1);
68
72
  }
69
73
  // Resolve auth token: --token flag takes priority over auth.json
70
74
  let token = options.token;
71
75
  if (!token) {
72
76
  if (!fs.existsSync(authPath)) {
73
- ui_1.log.error('❌ Not authenticated. Please run `bundle-drop login` or pass --token.');
77
+ ui_1.log.error(`❌ Not authenticated. Please run \`bundle-drop login\` or pass --token.\n` +
78
+ `Local setup: ${DOCS_INSTALLATION_URL}\n` +
79
+ `CI/CD tokens: ${DOCS_CI_CD_URL}`);
74
80
  process.exit(1);
75
81
  }
76
82
  token = JSON.parse(fs.readFileSync(authPath, 'utf-8')).token;
@@ -110,7 +116,7 @@ async function upload(platform, options) {
110
116
  if (platform === 'ios') {
111
117
  if (!version) {
112
118
  if (!options.plistFile) {
113
- ui_1.log.error('❌ Provide --version or --plist-file for iOS');
119
+ ui_1.log.error(`❌ Provide --version or --plist-file for iOS\nSee ${DOCS_UPLOADING_URL}`);
114
120
  process.exit(1);
115
121
  }
116
122
  try {
@@ -135,7 +141,7 @@ async function upload(platform, options) {
135
141
  version = parseAndroidVersionFromGradle(defaultPath);
136
142
  }
137
143
  else {
138
- ui_1.log.error('❌ Provide --version or --buildgradle-path for Android');
144
+ ui_1.log.error(`❌ Provide --version or --buildgradle-path for Android\nSee ${DOCS_UPLOADING_URL}`);
139
145
  process.exit(1);
140
146
  }
141
147
  }
@@ -185,7 +191,7 @@ async function upload(platform, options) {
185
191
  ui_1.log.label('Runtime Version (from config)', runtimeVersion);
186
192
  }
187
193
  if (!runtimeVersion) {
188
- ui_1.log.error('❌ runtimeVersion could not be determined');
194
+ ui_1.log.error(`❌ runtimeVersion could not be determined\nSee ${DOCS_RUNTIME_VERSION_URL}`);
189
195
  process.exit(1);
190
196
  }
191
197
  const zipPath = path.join(outputDir, `bundle-${platform}.zip`);
package/package.json CHANGED
@@ -1,12 +1,23 @@
1
1
  {
2
2
  "name": "@gfean/react-native-bundle-drop",
3
- "version": "0.3.2",
4
- "description": "react native ota by gFean",
3
+ "version": "0.3.3",
4
+ "nativeVersion": "0.3.2",
5
+ "description": "Over-the-air (OTA) updates for React Native — ship fixes instantly, no App Store or Play Store delays",
5
6
  "main": "lib/index.js",
6
7
  "types": "lib/index.d.ts",
7
- "author": " <> ()",
8
- "license": "UNLICENSED",
9
- "homepage": "https://github.com/GFean/react-native-bundle-drop",
8
+ "author": {
9
+ "name": "George Fean",
10
+ "url": "https://github.com/GFean"
11
+ },
12
+ "license": "ISC",
13
+ "homepage": "https://bundledrop.app",
14
+ "bugs": {
15
+ "url": "https://github.com/GFean/react-native-bundle-drop/issues"
16
+ },
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/GFean/react-native-bundle-drop.git"
20
+ },
10
21
  "exports": {
11
22
  ".": {
12
23
  "types": "./lib/index.d.ts",
@@ -18,6 +29,10 @@
18
29
  },
19
30
  "./package.json": "./package.json"
20
31
  },
32
+ "sideEffects": [
33
+ "./lib/bootstrap.js",
34
+ "./lib/index.js"
35
+ ],
21
36
  "scripts": {
22
37
  "clean": "rimraf lib dist",
23
38
  "build": "tsc -p tsconfig.build.json && node scripts/make-cli-executable.js",
@@ -63,9 +78,34 @@
63
78
  "ios/*.{m,h,mm,swift}",
64
79
  "BundleDrop.podspec",
65
80
  "react-native.config.js",
66
- "README.md",
67
- "CLIENT_README.md"
81
+ "README.md"
82
+ ],
83
+ "keywords": [
84
+ "react-native",
85
+ "react-native-ota",
86
+ "ota-updates",
87
+ "over-the-air",
88
+ "react-native-update",
89
+ "react-native-updates",
90
+ "bundle-updates",
91
+ "hot-update",
92
+ "codepush-alternative",
93
+ "expo-eas-update-alternative",
94
+ "react-native-deployment",
95
+ "mobile-updates",
96
+ "app-updates",
97
+ "live-updates",
98
+ "feature-rollout",
99
+ "staged-rollout",
100
+ "rollback",
101
+ "react-native-ci",
102
+ "react-native-release",
103
+ "react-native-production"
68
104
  ],
105
+ "peerDependencies": {
106
+ "react": ">=17.0.0",
107
+ "react-native": ">=0.71.0"
108
+ },
69
109
  "dependencies": {
70
110
  "adm-zip": "^0.5.16",
71
111
  "archiver": "^7.0.1",
package/CLIENT_README.md DELETED
@@ -1,411 +0,0 @@
1
- # Bundle Drop Client Quickstart (React Native)
2
-
3
- This guide is for app teams integrating `@gfean/react-native-bundle-drop` to fetch and apply OTA bundles.
4
-
5
- ## 1) Install and link
6
- ```bash
7
- yarn add @gfean/react-native-bundle-drop
8
- cd ios && pod install && cd ..
9
- ```
10
-
11
- Add the Android bootstrap side-effect import:
12
- ```js
13
- // index.js (entry)
14
- import '@gfean/react-native-bundle-drop/bootstrap';
15
- ```
16
-
17
- ### Metro config (resolve bundle.drop.config.js from node_modules)
18
- If Metro cannot find `bundle.drop.config.js` from packages, add an alias:
19
- ```js
20
- // metro.config.js
21
- const path = require('path');
22
-
23
- module.exports = {
24
- resolver: {
25
- extraNodeModules: {
26
- 'bundle-drop-config': path.resolve(__dirname, 'bundle.drop.config.js'),
27
- },
28
- },
29
- };
30
- ```
31
-
32
- ## 2) App config
33
- Add `bundle.drop.config.js` to your project root:
34
- ```js
35
- module.exports = {
36
- serverUrl: '<YOUR_BACKEND_URL>',
37
- runtimeVersion: {
38
- ios: '1.0.0',
39
- android: '1.0.0',
40
- },
41
- org: { slug: '<org-slug>' },
42
- project: {
43
- name: '<Project Name>',
44
- slug: '<project-slug>',
45
- apiKey: '<project-api-key>',
46
- },
47
- debugLocal: false,
48
- };
49
- ```
50
-
51
- ## 3) Minimal usage
52
- Startup (required):
53
- ```ts
54
- import '@gfean/react-native-bundle-drop/bootstrap';
55
- import { BundleDrop } from '@gfean/react-native-bundle-drop';
56
-
57
- BundleDrop.init({
58
- enabled: !__DEV__,
59
- environment: __DEV__ ? 'development' : 'production',
60
- policy: __DEV__ ? 'manual' : 'on-next-launch',
61
- channelName: 'General',
62
- onStatusUpdate: msg => console.log('[OTA]', msg),
63
- });
64
- ```
65
-
66
- `environment` is required and should come from your app runtime config (`.env`, schema loader, build flavor, etc.), not from `bundle.drop.config.js`. `enabled` defaults to `true`; set `enabled: false` when you want BundleDrop initialized in no-op mode for a given runtime.
67
-
68
- Recommended pattern:
69
- - Always call `BundleDrop.init(...)` during startup.
70
- - Use `enabled: false` when OTA should be off for a given runtime, such as Metro/dev or certain app flavors.
71
- - This keeps `useBundleDrop()` safe to mount while all OTA actions remain no-op.
72
-
73
- Manual UI example:
74
- ```ts
75
- import { useBundleDrop } from '@gfean/react-native-bundle-drop';
76
-
77
- const {
78
- channelName,
79
- setChannel,
80
- isEnabled,
81
- status,
82
- isBusy,
83
- installedInfo,
84
- pendingApply,
85
- checkLatest,
86
- downloadUpdate,
87
- applyUpdate,
88
- fetchAvailableChannels,
89
- availableChannels,
90
- } = useBundleDrop();
91
- ```
92
-
93
- If `BundleDrop.init(...)` is skipped, BundleDrop warns once and behaves like `enabled: false` until init happens.
94
-
95
- Quick check-only pattern:
96
- ```ts
97
- const { checkLatest, status } = useBundleDrop();
98
- await checkLatest();
99
- console.log(status);
100
- ```
101
-
102
- ## 4) Policies
103
- - `manual`: initialize local BundleDrop state but do not auto resolve/download/apply on startup.
104
- - `immediate`: download, stage, then apply immediately.
105
- - `on-next-launch`: download and stage now; apply on next launch.
106
-
107
- `checkOnly: true` can be combined with init when you want startup to perform only a resolve/check.
108
-
109
- ## 5) Channels
110
- - Keep channel names stable: `General`, `Beta`, `QA`.
111
- - `BundleDrop.init(...)` sets the initial runtime `channelName`.
112
- - `BundleDrop.setChannel(channelName)` or `useBundleDrop().setChannel(channelName)` can switch the active channel later.
113
- - `BundleDrop.getChannelName()` reads the active runtime channel outside React.
114
- - `fetchAvailableChannels()` retrieves available public channels for the configured project.
115
- - `fetchBundles({ channelName? })` lists downloadable bundles, defaulting to the active runtime channel.
116
-
117
- ## 6) Compatibility (`runtimeVersion`)
118
- - Define `runtimeVersion` per platform in `bundle.drop.config.js`.
119
- - Upload embeds `runtimeVersion` in metadata.
120
- - Client sends `runtimeVersion` during OTA resolve.
121
-
122
- ## 7) Targeted rollout (`currentUserProperties`)
123
- Use user properties to target cohorts from backend rollout rules.
124
-
125
- ```ts
126
- import {
127
- setUserProperty,
128
- setUserPropery,
129
- getUserProperties,
130
- getCurrentUserProperties,
131
- removeUserProperty,
132
- resetUserProperties,
133
- } from '@gfean/react-native-bundle-drop';
134
-
135
- await setUserProperty('QA Analyst');
136
- await setUserProperty('Beta Tester');
137
- await setUserPropery('QA Analyst'); // alias + duplicate ignored
138
-
139
- const propsA = await getUserProperties();
140
- const propsB = await getCurrentUserProperties();
141
-
142
- await removeUserProperty('Beta Tester');
143
- await resetUserProperties();
144
- ```
145
-
146
- Behavior:
147
- - Values are trimmed.
148
- - Duplicates are ignored.
149
- - Stored locally in `bundle-drop/user-properties.json`.
150
- - Sent automatically as `currentUserProperties` during OTA resolve checks.
151
-
152
- Environment behavior:
153
- - `environment` is sent automatically from `BundleDrop.init(...)`.
154
- - It is intended for analytics and future runtime targeting context.
155
- - Do not store environment in `bundle.drop.config.js`.
156
-
157
- Disabled behavior:
158
- - With `enabled: false`, BundleDrop does not perform startup OTA work.
159
- - `useBundleDrop()` exposes `isEnabled: false`.
160
- - OTA actions such as `checkLatest()`, `downloadUpdate()`, and `applyUpdate()` return disabled/no-op results instead of throwing.
161
-
162
- ## 8) Bundling/upload (CI/local)
163
- - Login (interactive, for local development):
164
- ```bash
165
- npx bundle-drop login
166
- ```
167
- - Upload Android:
168
- ```bash
169
- npx bundle-drop upload android --version 1.2.3 --channel General
170
- # or --buildgradle-path android/app/build.gradle
171
- ```
172
- - Upload iOS:
173
- ```bash
174
- npx bundle-drop upload ios --plist-file ios/Info.plist --channel General
175
- # or --version 1.2.3
176
- ```
177
- - Optional upload flags:
178
- - `--runtimeVersion x.y.z` — override runtime version
179
- - `--release-notes "text"` — attach release notes (max 2000 chars)
180
- - `--token <pat>` — authenticate with a Personal Access Token (skips `bundle-drop login`; ideal for CI/CD)
181
- - `--author <name>` — override the author name stored with the bundle
182
-
183
- ### CI/CD example
184
- ```bash
185
- npx bundle-drop upload android \
186
- --version 1.2.3 \
187
- --channel General \
188
- --token $BUNDLE_DROP_PAT \
189
- --author "CI Pipeline"
190
- ```
191
-
192
- ### Upload result file
193
-
194
- After a successful upload, the CLI writes a result file inside the module directory at `node_modules/@gfean/react-native-bundle-drop/dist/bundle-drop-result.json` with all upload details:
195
-
196
- ```json
197
- {
198
- "platform": "android",
199
- "appVersion": "1.2.3",
200
- "channel": "General",
201
- "orgSlug": "my-org",
202
- "projectSlug": "my-app",
203
- "runtimeVersion": "1.0.0",
204
- "bundleId": "abc123",
205
- "bundleVersion": 42,
206
- "bundleVersionLabel": "v42",
207
- "hash": "sha256hex...",
208
- "releaseNotes": "Bug fixes",
209
- "author": "CI Pipeline"
210
- }
211
- ```
212
-
213
- Use this in CI to read any field — no output parsing needed:
214
-
215
- ```bash
216
- BD_RESULT="node_modules/@gfean/react-native-bundle-drop/dist/bundle-drop-result.json"
217
-
218
- # Read any field
219
- jq -r '.bundleVersionLabel' "$BD_RESULT"
220
- jq -r '.appVersion' "$BD_RESULT"
221
- jq -r '.channel' "$BD_RESULT"
222
-
223
- # Azure DevOps
224
- echo "##vso[task.setvariable variable=BundleVersion]$(jq -r '.bundleVersionLabel' "$BD_RESULT")"
225
-
226
- # GitHub Actions
227
- echo "bundle_version=$(jq -r '.bundleVersionLabel' "$BD_RESULT")" >> "$GITHUB_OUTPUT"
228
- ```
229
-
230
- ## 9) Native setup (Android)
231
-
232
- The only change in your `MainApplication` (Kotlin or Java) is a single override that delegates bundle resolution to BundleDrop. It returns the OTA bundle path when available, otherwise falls back to the default.
233
-
234
- Kotlin:
235
- ```kt
236
- override fun getJSBundleFile(): String? =
237
- BundleDropModule.resolveJSBundleFile(applicationContext, super.getJSBundleFile())
238
- ```
239
-
240
- Java:
241
- ```java
242
- @Override
243
- protected String getJSBundleFile() {
244
- return BundleDropModule.resolveJSBundleFile(getApplicationContext(), super.getJSBundleFile());
245
- }
246
- ```
247
-
248
- ### A) Kotlin — older RN template (has `reactNativeHost`)
249
-
250
- If your `MainApplication.kt` already has a `reactNativeHost` block, add the import and the one-liner inside it:
251
-
252
- ```kt
253
- import com.bundledrop.BundleDropModule
254
-
255
- // inside your existing reactNativeHost object:
256
- override fun getJSBundleFile(): String? =
257
- BundleDropModule.resolveJSBundleFile(applicationContext, super.getJSBundleFile())
258
- ```
259
-
260
- ### B) Kotlin — RN 0.84+ template (ReactHost, no `reactNativeHost`)
261
-
262
- RN 0.84+ templates use `ReactHost` but don't expose `reactNativeHost`. BundleDrop needs `ReactNativeHost.getJSBundleFile()`, so you reintroduce `reactNativeHost` and wire `reactHost` from it.
263
-
264
- 1. Add imports (only if missing):
265
- ```kt
266
- import com.bundledrop.BundleDropModule
267
- import com.facebook.react.ReactHost
268
- import com.facebook.react.ReactNativeHost
269
- import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
270
- import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
271
- import com.facebook.react.defaults.DefaultReactNativeHost
272
- ```
273
-
274
- 2. Add `reactNativeHost` property (before `reactHost`):
275
- ```kt
276
- override val reactNativeHost: ReactNativeHost =
277
- object : DefaultReactNativeHost(this) {
278
-
279
- override fun getPackages() = PackageList(this).packages
280
- override fun getJSMainModuleName(): String = "index"
281
- override fun getUseDeveloperSupport(): Boolean = BuildConfig.DEBUG
282
-
283
- override val isNewArchEnabled: Boolean = BuildConfig.IS_NEW_ARCHITECTURE_ENABLED
284
- override val isHermesEnabled: Boolean = BuildConfig.IS_HERMES_ENABLED
285
-
286
- override fun getJSBundleFile(): String? =
287
- BundleDropModule.resolveJSBundleFile(applicationContext, super.getJSBundleFile())
288
- }
289
- ```
290
-
291
- 3. Ensure `reactHost` is created from `reactNativeHost`:
292
- ```kt
293
- override val reactHost: ReactHost by lazy {
294
- getDefaultReactHost(
295
- context = applicationContext,
296
- reactNativeHost = reactNativeHost
297
- )
298
- }
299
- ```
300
-
301
- 4. Ensure `onCreate()` calls:
302
- ```kt
303
- loadReactNative(this)
304
- ```
305
-
306
- ### C) Java — older RN template (`MainApplication.java`)
307
-
308
- Older React Native versions used Java instead of Kotlin. Add the import and the override inside your `ReactNativeHost` anonymous class:
309
-
310
- ```java
311
- import com.bundledrop.BundleDropModule;
312
-
313
- // inside your ReactNativeHost (or DefaultReactNativeHost) anonymous class:
314
- @Override
315
- protected String getJSBundleFile() {
316
- return BundleDropModule.resolveJSBundleFile(getApplicationContext(), super.getJSBundleFile());
317
- }
318
- ```
319
-
320
- Full example context:
321
-
322
- ```java
323
- private final ReactNativeHost mReactNativeHost =
324
- new DefaultReactNativeHost(this) {
325
- @Override
326
- protected List<ReactPackage> getPackages() {
327
- return new PackageList(this).getPackages();
328
- }
329
-
330
- @Override
331
- protected String getJSMainModuleName() {
332
- return "index";
333
- }
334
-
335
- @Override
336
- protected boolean getUseDeveloperSupport() {
337
- return BuildConfig.DEBUG;
338
- }
339
-
340
- @Override
341
- protected String getJSBundleFile() {
342
- return BundleDropModule.resolveJSBundleFile(getApplicationContext(), super.getJSBundleFile());
343
- }
344
- };
345
- ```
346
-
347
- > **Note:** The CLI command `npx bundle-drop init` detects your template (Kotlin/Java, older/new) automatically and applies the correct patch.
348
-
349
- ## 10) Native setup (iOS)
350
-
351
- The goal is to load the OTA bundle in **Release** (if present) and fall back to the embedded `main.jsbundle`, while keeping **Debug** on Metro.
352
-
353
- ### A) Swift (`AppDelegate.swift`)
354
-
355
- Add the import and replace the `bundleURL()` override:
356
-
357
- ```swift
358
- import BundleDrop
359
-
360
- override func bundleURL() -> URL? {
361
- #if DEBUG
362
- return RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
363
- #else
364
- if let url = BundleDropLocator.bundleURL() {
365
- return url
366
- }
367
- return Bundle.main.url(forResource: "main", withExtension: "jsbundle")
368
- #endif
369
- }
370
- ```
371
-
372
- ### B) Objective-C / ObjC++ (`AppDelegate.m` / `AppDelegate.mm`)
373
-
374
- Add the import and replace the `sourceURLForBridge:` method:
375
-
376
- ```objc
377
- #import <BundleDrop/BundleDrop-Swift.h>
378
-
379
- - (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
380
- {
381
- #if DEBUG
382
- return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
383
- #else
384
- NSURL *otaURL = [BundleDropLocator bundleURL];
385
- if (otaURL != nil) {
386
- return otaURL;
387
- }
388
- return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
389
- #endif
390
- }
391
- ```
392
-
393
- > **Note:** The CLI command `npx bundle-drop init` searches `ios/` recursively for `AppDelegate.swift`, `.mm`, or `.m` and patches whichever it finds first.
394
-
395
- ## 11) Public API snapshot
396
- Top-level exports:
397
- - `BundleDrop.init`
398
- - `BundleDrop.setChannel`
399
- - `BundleDrop.getChannelName`
400
- - `getAvailableChannels`, `checkForUpdate`, `getInstalledBundleInfo`
401
- - `getAvailableBundles`
402
- - `downloadUpdate`, `installBundle`
403
- - `getUpdateState`, `applyUpdate`
404
- - `useBundleDrop`
405
- - `BundleDropError`, `isBundleDropError`
406
- - `setUserProperty`, `setUserPropery`, `getUserProperties`, `getCurrentUserProperties`, `removeUserProperty`, `resetUserProperties`
407
-
408
- ## 12) Notes
409
- - Android asset resolver patching runs automatically.
410
- - `getUpdateState()` returns `{ hasBundle, info, pendingApply }`.
411
- - Set `debugLocal: true` to force localhost (`10.0.2.2` on Android).