--- name: nextpush description: Ship over-the-air (OTA) JavaScript and asset updates to React Native and Expo apps with NextPush, a hosted CodePush-compatible service that also speaks the Expo Updates protocol. Use when a user wants to add OTA updates to a React Native or Expo app, release, promote or roll back an update, migrate from App Center CodePush or EAS Update, set up the nextpush CLI (including sign-in without a browser), or manage NextPush apps, deployments, keys and billing. license: MIT metadata: version: "1.0" canonical: https://nextpush.center/skill.md docs: https://docs.nextpush.dev cli: nextpush-cli (npm), 1.2.0 or newer --- # NextPush NextPush (https://nextpush.center) delivers over-the-air updates to mobile apps: the JavaScript bundle and assets change without a new store release. It serves two protocols from one account: - **CodePush** for React Native apps that use a CodePush SDK. NextPush is the hosted replacement for Microsoft App Center CodePush: same SDK contract, same CLI command shapes, one server URL changes. - **Expo Updates** (beta) for Expo apps that use `expo-updates`; the app points `updates.url` at NextPush instead of EAS Update. Vocabulary: an **app** belongs to an owner (`/`); each app has **deployments** (Staging and Production by default) and each deployment has a **deployment key** that is baked into the native build; a **release** is one uploaded update, labelled `v1`, `v2`, ... per deployment. Billing counts update downloads, not monthly active users; the free plan needs no card. URLs: dashboard `https://nextpush.center`, API `https://api.nextpush.center`, docs `https://docs.nextpush.dev`, status `https://status.nextpush.dev`. ## Rules for agents 1. **Run `nextpush whoami` first.** If it fails, sign in (next section). Never ask the user to paste an access key into chat or into source files. 2. **Default to Staging.** Release to Production only when the user asks for it explicitly, and confirm app, deployment and target binary version in one sentence before running the command. Rollbacks and `--mandatory` releases also need an explicit go-ahead. 3. **Never commit secrets.** Deployment keys are fine in native config files (they are public identifiers). Access keys (`ak_...`), the CLI config file and `.nextpush.config` are secrets: keep them out of git and out of your output. 4. **Do not guess flags.** When unsure, run `nextpush --help` and quote the real option. The reference at the end of this file is correct for CLI 1.2.0. 5. **Report what happened**: the label (`v7`), deployment, target version, rollout percentage and the `deployment history` line after a release. 6. **Prefer the CLI over the dashboard.** For anything the CLI cannot do (billing, invitations, deleting an account) use `nextpush dashboard` or `nextpush billing`, which open the right page already signed in, and tell the user what to click. ## Install and sign in ```bash npm install -g nextpush-cli # Node.js 18+; the command is `nextpush` nextpush --version # 1.2.0 or newer for --email, billing, dashboard, release-expo nextpush whoami # prints the e-mail of the signed-in account, or an error ``` Sign-in options, in order of preference for an agent: ```bash # 1. E-mail code, two commands, no browser or terminal prompt needed. nextpush login --email you@company.com # -> "We sent a 6-digit sign-in code to you@company.com." Ask the user for the code, then: nextpush login --email you@company.com --code 123456 # Creates the account on first sign-in. The code lives 10 minutes and works once. # 2. Existing access key (the user created it in Settings or with `nextpush access-key add `). nextpush login --accessKey # 3. Browser flow (GitHub, Google or e-mail on the website); a human copies the key it shows. nextpush login ``` Notes: in an interactive terminal `nextpush login --email` asks for the code right away. The session is stored in `~/com.nextpush.center/.nextpush.config` (`%LOCALAPPDATA%\com.nextpush.center\` on Windows). `nextpush logout` deletes it. "You are already logged in from this machine" means a session exists: run `nextpush whoami` and continue, or `nextpush logout` first. ## Apps, deployments and keys ```bash nextpush app ls # apps you own or collaborate on, as / nextpush app add MyApp-iOS -o ios # one NextPush app per platform is the convention nextpush app add MyApp-Android -o android nextpush deployment ls / -k # deployments with their keys (-k shows the keys) nextpush deployment add / Beta nextpush deployment history / Production # releases, newest last, with rollout and metrics nextpush collaborator add / teammate@company.com ``` App names are `/` in every command. When the user has one app per platform, name them `MyApp-iOS` and `MyApp-Android` and use the matching deployment key in each native project. ## Set up a React Native app (CodePush SDK) Use the community SDK; the Microsoft package (`react-native-code-push` 9.x) is deprecated and does not run on the New Architecture. ```bash npm install @code-push-next/react-native-code-push cd ios && pod install && cd .. ``` Version guide: React Native 0.76–0.79 → `@code-push-next/react-native-code-push` 10.0+, 0.80 → 10.1+, 0.81 → 10.3+, 0.82 and newer → 10.4+ (New Architecture only). Follow the package README for the native wiring (`MainApplication`, `AppDelegate`), then point it at NextPush: Android `android/app/src/main/res/values/strings.xml`: ```xml dk_... https://api.nextpush.center ``` iOS `ios//Info.plist`: ```xml CodePushDeploymentKey dk_... CodePushServerURL https://api.nextpush.center ``` Expo (bare workflow or prebuild) projects can use the config plugin instead of editing native files: add `@code-push-next/react-native-code-push/expo` to `plugins` in `app.json` with the deployment keys and `serverUrl: "https://api.nextpush.center"`, then run `npx expo prebuild`. Wrap the root component with `codePush(...)` as the README shows. A debug build attached to Metro does not apply updates; test with a release build (`npx react-native run-android --mode release` or an Xcode Release scheme). Release: ```bash nextpush release-react / ios -d Staging --description "Fix login crash" nextpush release-react / android -d Staging --description "Fix login crash" ``` `release-react` bundles with the project's React Native and uploads the result. Useful options: `-t "1.4.x"` to target a binary version range (default: the version in Info.plist / build.gradle), `-m` mandatory, `--rollout 25%` for a staged rollout, `--dev` for a development bundle, `--entryFile`, `--bundleName`, `--plistFile`, `--gradleFile`, `--useHermes` (`-h`) to force Hermes bytecode when the CLI cannot detect it, `--privateKeyPath` (`-k`) to sign the bundle. ## Set up an Expo app (expo-updates) Requirements: Expo SDK 52 or newer, a development build or release build (Expo Go cannot load updates from a custom server). `app.json`: ```json { "expo": { "runtimeVersion": "1.0.0", "updates": { "url": "https://api.nextpush.center/expo//manifest", "enabled": true, "checkAutomatically": "ON_LOAD", "fallbackToCacheTimeout": 0 } } } ``` - Use the Production deployment key for store builds and Staging for internal builds. - `runtimeVersion` must be a plain string, or pass the resolved value with `--runtimeVersion` when releasing (the CLI cannot evaluate policies). Bump it whenever native code or native dependencies change. - Do not set `codeSigningCertificate`; NextPush does not sign manifests yet. - Rebuild the native app (`npx expo prebuild`, `npx expo run:ios|android` or EAS Build) after changing these values. Release (runs `npx expo export` for you): ```bash nextpush release-expo / -d Staging nextpush release-expo / -d Production --runtimeVersion 1.4.0 --description "Fix login" nextpush release-expo / --platform ios # one platform nextpush release-expo / --dist ./dist # upload an existing export ``` Beta limits: no code signing, no rollback directive (disable a release instead and publish a new one), no dashboard page for Expo releases yet, exact runtime-version match per platform, no staged rollout for Expo releases. Full details: https://docs.nextpush.dev/expo-updates. ## Migrate from App Center CodePush The SDK contract is unchanged, so the move is configuration: 1. Replace `react-native-code-push` with `@code-push-next/react-native-code-push` (or keep the Microsoft SDK on old-architecture apps if it still builds). 2. Add `CodePushServerUrl` / `CodePushServerURL` = `https://api.nextpush.center` to strings.xml and Info.plist (see above). Keep or replace the deployment keys with the NextPush ones. 3. Replace `appcenter codepush` with `nextpush` in scripts: `appcenter codepush release-react -a owner/App -d Production` becomes `nextpush release-react owner/App ios -d Production` (NextPush takes the platform as a positional argument because apps are per platform). 4. Ship a store release with the new URL; devices on the new binary start checking NextPush. The App Center API was retired in 2025, so the CLI has no import command; if the user still has App Center data to bring over, point them to the dashboard's "Import data from App Center" entry and let them run it. ## Release workflow that keeps users safe ```bash # 1. Staging nextpush release-react / ios -d Staging --description "Fix login" nextpush deployment history / Staging # 2. Test on a release build pointed at the Staging key, then promote the same bundle nextpush promote / Staging Production --rollout 10% nextpush patch / Production --rollout 50% # widen the rollout nextpush patch / Production --rollout 100% # 3. Something is wrong nextpush rollback / Production # back to the previous release nextpush rollback / Production --targetRelease v12 nextpush patch / Production --disabled true # stop serving the latest release # 4. Metadata nextpush patch / Production --label v13 --description "..." --mandatory true ``` Target binary versions follow semver: `-t 1.4.0` exact, `-t "~1.4.0"` patch range, `-t "^1.4.0"` minor range, `-t "*"` every version (avoid). A release only reaches apps whose binary version matches. ## Verify and troubleshoot - `nextpush deployment history / ` shows each release with install metrics (active, pending, rolled back); it is the first thing to check when "the update is not arriving". - `nextpush debug android` / `nextpush debug ios` tails the CodePush logs of a running emulator or simulator. - Update never arrives: the app is a debug build attached to Metro; the deployment key in the native config belongs to another deployment; the binary version does not match `-t`; the release is disabled or still rolling out; the server URL is missing (the SDK then talks to the retired App Center host). - `Authentication failed` / `Invalid access key`: the stored session expired (keys last 60 days); run `nextpush login --email ...` again. - `Bundle limit reached`: the account is at its plan's download/bundle limit; open `nextpush billing` and let the user decide. - `"runtimeVersion" in your Expo config is a policy`: pass `--runtimeVersion` with the resolved value (for `appVersion` it is `expo.version`; for `fingerprint` run `npx expo-updates fingerprint:generate`). ## Dashboard and billing from the terminal ```bash nextpush dashboard # opens https://nextpush.center/apps signed in (one-time link, 60 s) nextpush dashboard /settings/profile # any dashboard path nextpush billing # Settings > Billing: plan, add-ons, usage nextpush billing --plan plus # checkout of a plan: individuals | plus | enterprise | unlimited | additional-updates nextpush billing --no-browser # print the link for the user instead of opening a browser ``` The link signs the browser in through a one-time code; the CLI access key never leaves the machine. When the user asks to upgrade, buy more updates or fix a payment, run `nextpush billing` (or `--no-browser` and show the link) and stop; payments are the user's action. ## Command reference (CLI 1.2.0) | Command | Purpose | | --- | --- | | `nextpush login [--email ] [--code <6 digits>] [--accessKey ]` | Sign in (browser, e-mail code or key) | | `nextpush register [--email ] [--code <6 digits>]` | Create an account (same flows as login) | | `nextpush logout`, `nextpush whoami` | End the session / show the account | | `nextpush app add -o `, `app ls`, `app rename`, `app rm`, `app transfer ` | Apps | | `nextpush deployment add\|ls\|rm\|rename\|history\|clear / ...` (`ls -k` shows keys) | Deployments | | `nextpush release-react / [-d ] [-t ] [-m] [--rollout %] [--description ]` | Bundle and release a React Native update | | `nextpush release-expo / [-d ] [--runtimeVersion ] [--platform all\|ios\|android] [--dist ]` | Export and release an Expo update | | `nextpush release / [-d ]` | Release a prebuilt bundle folder | | `nextpush promote / [--rollout %] [-t ] [-m] [--description ]` | Copy the latest release to another deployment | | `nextpush rollback / [--targetRelease