capawesome-live-update-migration

Files (2)

• SKILL.md
• metadata.json

SKILL.md (first lines)

# Capawesome Live Update Migration

Move a Capacitor app from Capawesome Cloud live updates to `@capgo/capacitor-updater` with the smallest useful change set.

Product source of truth: `https://capgo.app/docs/upgrade/from-capawesome-to-capgo/` (website source: `apps/docs/src/content/docs/docs/upgrade/from-capawesome-to-capgo.mdx`).

## When to Use

TRIGGER when:
- The repo references `@capawesome/capacitor-live-update`, `LiveUpdate.` calls, `plugins.LiveUpdate`, or `@capawesome/cli` / `capawesome` upload commands in scripts or CI.
- The user asks to move from Capawesome Cloud to Capgo, or for a Capgo vs Capawesome live-update comparison.
- An app already uses Capgo elsewhere and should consolidate live updates.

Do not use for:
- Ionic Appflow (`@capacitor/live-updates`, `cordova-plugin-ionic`) -> `ionic-appflow-migration`.
- No prior live-update provider -> `capgo-live-updates`.
- Channel design, staged rollouts, promotion -> `capgo-release-workflows`.

## Live Project Snapshot

Detected live-update packages:
!`node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capawesome/')||name==='@capgo/capacitor-updater'||name==='@capgo/cli'||name==='@capacitor/core')out.push(section+'.'+name+'='+version)}}for(const [name,cmd] of Object.entries(pkg.scripts||{})){if(/capawesome|live-update|capgo/i.test(cmd))out.push('scripts.'+name+'='+cmd)}console.log(out.sort().join('\n'))"`

## Procedure

### Step 1: Detect the existing setup

```bash
rg -n "capawesome|LiveUpdate|capacitor-live-update|CapacitorUpdater|@capgo/capacitor-updater" \
  -g '!node_modules' package.json capacitor.config.* src ios android .github .gitlab-ci.yml 2>/dev/null
```

Record: installed package version, `plugins.LiveUpdate` settings, where `LiveUpdate.ready()` is called, any manual `sync`/`fetchLatestBundle`/`downloadBundle`/`setNextBundle`/`reload` flow, splash-screen logic tied to updates, CI upload commands and secret names.

### Step 2: Swap packages

```bash
npm uninstall @capawesome/capacitor-live-update
npm install @capgo/capacitor-updater
npx cap sync
```

This is the only mandatory package swap. The updater runtime ships as native code in the plugin. Keep other `@capawesome/*` plugins untouched.

### Step 3: Minimal Capgo config

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

const config: CapacitorConfig = {
  // appId, appName, webDir unchanged
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      autoDeletePrevious: true,
      // periodCheckDelay: 600, // optional: seconds between checks while open (minimum 600)
    },
  },
};

export default config;
```

`periodCheckDelay` is in seconds, not milliseconds; values below 600 are raised to 600.

| Capawesome `plugins.LiveUpdate` | Capgo |
|---|---|
| `appId` | Capgo app (created by `npx @capgo/cli@latest init`, keyed on the Capacitor `appId`); set `CapacitorUpdater.appId` only for multi-app binaries |
| `autoUpdateStrategy: 'background'` | `autoUpdate: true` |
| `autoUpdateStrategy: 'none'` (manual `sync`) | `autoUpdate: true` unless custom timing is a product requirement; otherwise `autoUpdate: false` + manual APIs |
| `defaultChannel` | Channel rules in Capgo dashboard/CLI, or `defaultChannel` for a per-build override |
| `autoDeleteBundles` | `autoDeletePrevious: true` |
| `autoBlockRolledBackBundles` | Built in: failed bundles are marked and not retried (`autoDeleteFailed`) |
| `readyTimeout` (ms) | `appReadyTimeout` (ms, default 10000) |
| `publicKey` (signing) | Capgo end-to-end encryption: `npx @capgo/cli@latest key create`, then `publicKey` is written to config |
| `httpTimeout` (ms) | `responseTimeout` (seconds, default 20) |
| `serverDomain` | Not needed for Capgo Cloud; `updateUrl`/`statsUrl`/`channelUrl` for self-hosting |

### Step 4: Startup hook

Replace `LiveUpdate.ready()` with:

```ts
import { CapacitorUpdater } from '@capgo/capacitor-updater';

void CapacitorUpdater.notifyAppReady();
```

Call it once the app shell renders, not behind login or a network request. If it is not called within `appReadyTimeout`, Capgo rolls back to the previous working bundle.

### Step 5: Delete unneeded JavaScript glue

Remove code that only exists to: check on resume, download in the background, set the next bundle, reload after download, hide the splash only after update checks, retry failed downloads, or clean up old bundles. Capgo's native auto-update does all of that. Keep manual calls only for explicit product requirements (custom "update available" UI, user-chosen channels).

### Step 6: Map optional manual APIs

| Capawesome `LiveUpdate.*` | Capgo `CapacitorUpdater.*` | Keep only if |
|---|---|---|
| `ready()` | `notifyAppReady()` | always |
| `sync()` | not needed (`autoUpdate: true`); `triggerUpdateCheck()` to force a check | custom timing |
| `fetchLatestBundle()` | `getLatest()` | custom discovery UI |
| `downloadBundle()` | `download({ url, version })` | app controls download timing |
| `setNextBundle()` | `next({ id })` | apply on next start |
| `reload()` | `reload()`, or `set({ id })` to switch and reload | apply immediately |
| `getCurrentBundle()` | `current()` | diagnostics |
| `getBundles()` / `getDownloadedBundles()` | `list()` | diagnostics |
| `deleteBundle()` | `delete({ id })` | manual cleanup |
| `reset()` | `reset()` | support tooling |
| `setChannel()` / `getChannel()` / `fetchChannels()` | `setChannel()` / `getChannel()` / `listChannels()` | user-selectable channels (enable self-assignment on the channel) |
| `setCustomId()` / `getDeviceId()` | `setCustomId()` / `getDeviceId()` | support/targeting |
| `getVersionName()` / `getVersionCode()` | `getBuiltinVersion()` | diagnostics |
| `addListener('nextBundleSet' / 'reloaded' / 'downloadBundleProgress')` | `addListener('setNext' / 'appReloaded' / 'download')` | UI feedback |

### Step 7: Replace upload automation

```bash
npx @capgo/cli@latest login <CAPGO_API_KEY>   # CI: set CAPGO_TOKEN instead
npm run build
npx @capgo/cli@latest bundle upload --path <webDir> --channel production

From Cap-go/capgo-skills, MIT.

More from Cap-go/capgo-skills