Migrate from Capawesome Cloud

A Capacitor app moves its over-the-air (OTA) updates from Capawesome Cloud to HotCodePush by replacing @capawesome/capacitor-live-update with @hotcodepush/capacitor-live-updates at its next store release. That store build is the switch, and older builds keep taking Capawesome Cloud bundles until their users move. What differs, side by side, is on the site's Capawesome Cloud alternative page.

Which product fitsCopy Anchor Link

Stay on Capawesome Cloud when you want native builds, store publishing and updates in one console on one plan. Stay too for Electron, Ionic Portals, self-hosted bundles, a reverse proxy or Capacitor 6, which HotCodePush lacks.

Move when the OTA updates are your reason to move. HotCodePush adds a readiness gate with rollback on by default, the fingerprint instead of a channel per native release, auto-pausing rollouts and attribute targeting. Which of the two products is for you compares them.

Combine them by keeping the native builds and the store deployments in Capawesome Cloud and dropping the web builds, the channel deployments and the plugin. Capawesome Cloud is that pipeline, and the rest of this page moves the updates to HotCodePush.

AI-assisted migration (recommended)Copy Anchor Link

Install the HotCodePush skills:

npx skills add hotcodepush-team/skills

Then paste the prompt into your coding agent:

Migrate this app from Capawesome Cloud to HotCodePush: install the skills with `npx skills add hotcodepush-team/skills`, then run the hotcodepush-migrate skill, following https://hotcodepush.com/docs/migrate/capawesome-cloud.

The agent removes the Capawesome plugin, runs init, maps channels, config keys, SDK calls and binary ranges, and reports a checklist for the store release. It never touches Capawesome Cloud, and the first release waits for the store build. Agent skills explains what the agent does.

PrerequisitesCopy Anchor Link

• You have a HotCodePush account and an organization. npx hotcodepush init creates both, as the quickstart shows.
• The app is a Capacitor app on a supported major, listed on Supported versions. An app on the plugin's v6-lts line upgrades Capacitor first.
• A store release lies ahead, since the swap ships in a native build.
• Node.js is on every machine that makes a native build, a Capawesome Cloud build included, since the build step runs the CLI on that machine.

StepsCopy Anchor Link

If you already removed the plugin and ran init, skip to step 4.

1. Freeze a branch for the old buildsCopy Anchor Link

git branch capawesome-cloud-fleet

A bundle built from the migrated code imports a native module the old binaries lack. Hotfixes for them come from a branch that keeps the old plugin, and private.pem stays where that pipeline reads it.

2. Remove the Capawesome pluginCopy Anchor Link

npm uninstall @capawesome/capacitor-live-update

Delete the LiveUpdate block from plugins in capacitor.config.ts and the /// <reference types="@capawesome/capacitor-live-update" /> line, then CapawesomeLiveUpdateDefaultChannel from Info.plist and capawesome_live_update_default_channel from build.gradle. Replace every call and listener per the SDK calls below, then run npx cap sync.

3. Run initCopy Anchor Link

npx hotcodepush init

init signs you in, picks or creates the organization and the app with its production channel, installs @hotcodepush/capacitor-live-updates, writes hotcodepush.json and wires the build step. The Capacitor SDK's Installation page has the manual steps.

It asks whether to generate a signing key, which Sign your bundles explains. A signing app declines and keeps its pair: npx hotcodepush signing-key add --private-key-path private.pem registers the public key and writes publicKeys. The publicKey string itself does not carry over. Decline the first release for now.

Then import the package in the app's entry file, where ready() was, even when no call follows:

import '@hotcodepush/capacitor-live-updates';

The import reports the first render, which is what ready() did. An app that imports the package late, or not at all, confirms no update, and every one is rolled back after readyTimeoutSeconds.

4. Create the channels your Capawesome channels hadCopy Anchor Link

production exists and takes the place of default. The versioned channels, production-<versionCode>, collapse into it: the fingerprint keeps a release away from a build it was not made for. Each further channel becomes one here:

npx hotcodepush channel create --name beta --discoverable

--discoverable lets setChannel({ name }) find the channel by name, as Channels describes. Without it the channel is reachable by its id alone. A build that set defaultChannel or the native key sets channel in hotcodepush.json or HOTCODEPUSH_CHANNEL instead, as Set up environments and tenants shows.

5. Ship the store release that carries the SDKCopy Anchor Link

Build and submit the release as before. The build step runs binary create inside the build and registers it with its fingerprint, so the machine needs npx hotcodepush login or HOTCODEPUSH_TOKEN. A Capawesome Cloud build takes the token as an environment secret, as Capawesome Cloud shows, and under CI a build without one fails.

6. Release from your pipelineCopy Anchor Link

npm run build && npx hotcodepush release create --bundle-version "$(git rev-parse --short HEAD)" --yes

This line replaces npx @capawesome/cli apps:liveupdates:upload --app-id <id> --path dist --channel production or the cloud-live-update-action step. GitHub Actions has the CLI step. With HOTCODEPUSH_TOKEN and, for a signing app, HOTCODEPUSH_SIGNING_KEY in the environment, it is the whole pipeline step. The command reads webDir from capacitor.config, and Ship every commit is the pipeline it sits in.

Open the app on a device that runs the new store build: the release applies within about a minute (How an update reaches a device). If nothing happens, see Troubleshooting.

7. Run both until the fleet movesCopy Anchor Link

A binary carries one plugin: a Capawesome Cloud bundle never reaches a HotCodePush build, and the reverse. Keep the Capawesome Cloud pipeline while old builds have users. Its console's MAU shows how many still check in. Then end the plan, unless the native builds still run on it.

CLI commandsCopy Anchor Link

A bundle is numbered per app with a free version label, and a release puts it on a channel, numbered per channel (Bundles and releases). The CLI reference lists every command.

What maps to whatCopy Anchor Link

The Capacitor SDK's Configuration page lists every key with its type and default.

SDK callsCopy Anchor Link

The Capacitor SDK's API page has every method, event and type. On the web every method rejects with Capacitor's UNIMPLEMENTED error, as the plugin's did, so the Capacitor.isNativePlatform() guards carry over.

Before and afterCopy Anchor Link

The LiveUpdate block leaves capacitor.config.ts:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  plugins: { 
    LiveUpdate: { 
      appId: '00000000-0000-0000-0000-000000000000', 
      autoUpdateStrategy: 'background', 
      defaultChannel: 'production', 
      readyTimeout: 10000, 
    }, 
  }, 
};

export default config;

hotcodepush.json takes its place at the project root. The background strategy equals the defaults, so two keys are the whole file:

{
  "appId": "<your app id>",
  "channel": "production"
}

ready() goes, and the import takes its place in the entry file:

import { LiveUpdate } from '@capawesome/capacitor-live-update'; 
import '@hotcodepush/capacitor-live-updates'; 

await LiveUpdate.ready(); 

What differsCopy Anchor Link

• The readiness gate is always on: the plugin's readyTimeout was off unless you set it. Here readyTimeoutSeconds is 10 by default and has no off switch (Configuration).
• A rollback lands on the last confirmed release, or on the embedded bundle without one. It blocks the failed bundle on that device (Roll back a release).
• release rollback is mandatory by default: running apps restart as soon as they have it, where a rollback deployment applied at the next launch. Pass --mandatory false, or set mandatoryApplyStrategy: manual, to let them wait.
• Protected means a role, not a signature: --protected limits changes to Owners and Admins, and a registered key refuses every unsigned upload for the app.
• No server-side default channel and no forced channel: the build carries its channel, and HotCodePush never assigns one. A tester switches with setChannel() or a link (Switch channels by link), and release create --device <id> targets one device.
• No channel per call, and a name needs --discoverable: sync({ channel }) has no counterpart, and anyone holding the app id can read a discoverable name.
• getChannel().name is null on the build's channel: the build carries the channel by id alone, so code that compared the name reads id or source instead.
• The fingerprint replaces versioned channels and per-platform build ranges: a release never lands on a build whose native code differs. A --binary-version range compares the store version, with the build number as its fourth component, for both platforms at once. See Compatibility.
• A bundle is at most 512 MB, where Capawesome Cloud took 1 GB. Retention is 90 days on every plan. Limits and fair use lists every limit.
• Gone with no replacement: custom properties, fetchChannels(), setConfig({ appId }) and cloud web builds have no counterpart.

Next stepsCopy Anchor Link

• Roll out gradually: start a release small, let it progress and let auto-pause stop a bad one.
• Sign your bundles covers the pair you brought along, and the store build that refuses an unsigned release.
• Capawesome Cloud runs the native builds and the store deployments beside the OTA updates from HotCodePush.
• Capacitor SDK reference documents every hotcodepush.json key, method, event, type and reason of the SDK you installed.