ionic-appflow-migration

Q: How do I install ionic-appflow-migration?

Run npx skills add https://github.com/cap-go/capgo-skills --skill ionic-appflow-migration in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ionic-appflow-migration/ (personal) or .claude/skills/ionic-appflow-migration/ (project).

by cap-goCode Quality & Workflow

Migrates an Ionic or Capacitor project off Ionic Appflow (access ends Dec 31, 2027). Use when the repo contains @capacitor/live-updates, cordova-plugin-ionic, a plugins.LiveUpdates block (appId, channel, autoUpdateMethod, maxVersions), LiveUpdates.sync()/reload() calls, ionic deploy or appflow CLI commands, .io-config.json, or Appflow build/store-deploy workflows, and the user wants Capgo live updates, Capgo Cloud Build or repo-owned CI builds, and repo-owned store publishing. Maps Appflow channels, update strategies, and API calls to @capgo/capacitor-updater. Do not use for Ionic Enterprise plugins such as Identity Vault, Auth Connect, or Secure Storage (ionic-enterprise-sdk-migration), Capawesome live updates (capawesome-live-update-migration), or a fresh Capgo setup with no Appflow history (capgo-live-updates).

Installs: 654
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/cap-go/capgo-skills --skill ionic-appflow-migration

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads ionic-appflow-migration automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Ionic Appflow Migration

Replace each Appflow feature the project uses - Live Updates, native cloud builds, store deployment - and remove Appflow only after each replacement is verified.

Context: Ionic stopped selling Appflow in February 2025; existing customers keep access until December 31, 2027 with no new features. Plan the migration well before that date.

When to Use

TRIGGER when:

package.json has @capacitor/live-updates or cordova-plugin-ionic.
capacitor.config.* has plugins.LiveUpdates, or config.xml / Info.plist / strings.xml hold Appflow deploy keys (APP_ID, CHANNEL_NAME, UPDATE_METHOD, IonAppId, IonChannelName).
CI calls ionic deploy, appflow, ionic package build, or the Appflow dashboard triggers builds and store uploads.

Do not use for:

@ionic-enterprise/* plugins -> ionic-enterprise-sdk-migration.
Capawesome Cloud -> capawesome-live-update-migration.
Greenfield Capgo setup -> capgo-live-updates.

Live Project Snapshot

Detected Appflow-related packages and scripts: !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==='@capacitor/live-updates'||name==='cordova-plugin-ionic'||name.includes('appflow')||name==='@ionic/cli'||name==='@capgo/capacitor-updater'||name==='@capacitor/core')out.push(section+'.'+name+'='+version)}}for(const [name,cmd] of Object.entries(pkg.scripts||{})){if(/appflow|ionic deploy|ionic package|live-updates/i.test(cmd))out.push('scripts.'+name+'='+cmd)}console.log(out.join('\n'))"

Possible Appflow config and workflow paths: !find . -maxdepth 4 -not -path '*/node_modules/*' \( -name '.io-config.json' -o -name 'ionic.config.json' -o -name 'config.xml' -o -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' -o -path './.github/workflows/*' -o -name '.gitlab-ci.yml' -o -name 'appflow.config.json' \)

Procedure

Step 1: Inventory (report before editing)

rg -n "@capacitor/live-updates|cordova-plugin-ionic|LiveUpdates|IonAppId|IonChannelName|UPDATE_METHOD|CHANNEL_NAME|ionic deploy|appflow|dashboard.ionicframework.com|ionic.io/appflow" \
  -g '!node_modules' .

Record per feature:

Live Updates: SDK in use, Appflow app ID, channels and which binaries point at them, update method (background, none, always-latest on resume, force update), maxVersions, any code calling sync(), download(), extract(), reload().
Native builds: build stack, signing certificates/profiles and keystores stored in Appflow, environment variables, native config overrides.
Store deploys: TestFlight / Play destinations and tracks.

Ask the user to export signing credentials from Appflow (or confirm they have originals) before deleting anything there.

Step 2: Live Updates -> Capgo

npm uninstall @capacitor/live-updates   # or: npm uninstall cordova-plugin-ionic
npm install @capgo/capacitor-updater
npx cap sync

For cordova-plugin-ionic, also remove its <plugin>/<variable> entries from config.xml and any Ion* keys from native files.

Replace the config block:

// capacitor.config.ts
plugins: {
  // remove LiveUpdates: { appId, channel, autoUpdateMethod, maxVersions }
  CapacitorUpdater: {
    autoUpdate: true,
    autoDeletePrevious: true,
  },
},

Appflow	Capgo
`appId`	Capgo app created with `npx @capgo/cli@latest init` (uses `appId` from `capacitor.config`)
`channel`	Capgo channel (dashboard/CLI); set default channel server-side, or `defaultChannel` in config for per-build overrides
`autoUpdateMethod: 'background'`	`autoUpdate: true` (default behaviour: download in background, apply on next start)
`autoUpdateMethod: 'none'` + manual `sync()`	Keep `autoUpdate: true` unless the product needs custom timing; otherwise `autoUpdate: false` + manual API
`maxVersions`	`autoDeletePrevious: true` plus server-side bundle retention
Binary-version targeting	Channel per native major, or `--min-update-version` / metadata strategy (`capgo-release-workflows`)
Force update	Mark bundle/channel behaviour in Capgo and listen for `majorAvailable` or use `directUpdate`

Add the one required hook once the app shell renders:

import { CapacitorUpdater } from '@capgo/capacitor-updater';
void CapacitorUpdater.notifyAppReady();

Without it Capgo treats the bundle as broken and rolls back.

API mapping (keep manual calls only if the product needs custom UI or timing):

Appflow (`@capacitor/live-updates`)	Capgo
`LiveUpdates.sync()`	Not needed with `autoUpdate: true`; manual: `CapacitorUpdater.getLatest()` + `download()`
`LiveUpdates.reload()`	`CapacitorUpdater.set({ id })` (applies and reloads) or `reload()`
resume listener calling `sync()`	Remove; auto-update checks on resume
`SplashScreen.hide()` after sync	Plain `SplashScreen.hide()` after app boot; optional `appReady` listener

Upload the first bundle to a test channel:

npm run build
npx @capgo/cli@latest bundle upload --channel development

Step 3: Native cloud builds

Two replacements; ask which the user prefers:

Capgo Cloud Build: npx @capgo/cli@latest build credentials save --platform ios|android ..., then npx @capgo/cli@latest build request <appId> --platform ios|android. Details in capgo-native-builds.
Repo-owned CI (GitHub Actions, GitLab, Fastlane): capacitor-ci-cd.

Carry over environment variables, build-time config, and signing inputs exactly; change one thing at a time.

Step 4: Store publishing

Capgo Cloud Build can upload to TestFlight / Play when store credentials are saved; otherwise use CI upload steps (capacitor-ci-cd) or manual submission (capacitor-app-store). Keep bundle IDs, Play tracks, and credentials unchanged.

Step 5: Cut over and clean up

Ship a native build containing @capgo/capacitor-updater to the stores. Devices on older binaries keep pulling from Appflow until they update - keep Appflow channels live until adoption is high enough.
Publish web updates to both systems during the overlap, or freeze Appflow at the last bundle shipped with the new binary.
Remove Appflow packages, plugins.LiveUpdates, .io-config.json references, Appflow CI jobs, and secrets once no supported binary depends on them.

Verification

rg -n "@capacitor/live-updates|cordova-plugin-ionic|LiveUpdates\\." -g '!node_modules' . returns nothing (after cleanup).
Fresh install of the new binary: logs show notifyAppReady called; Capgo dashboard shows the device.
Upload a test bundle to a non-production channel; device downloads and applies it on next start.
Upload a deliberately broken bundle (no notifyAppReady) to the test channel; device rolls back.
New native build pipeline produces signed IPA/AAB with the same bundle ID and a higher build number.

Error Handling

Problem	Fix
App rolls back every update	`notifyAppReady()` not reached (called too late, behind login, or code path throws); call it right after the shell renders
`Cannot find API key in local folder or global, please login first` from the Capgo CLI	`npx @capgo/cli@latest login <apikey>` locally, or `CAPGO_TOKEN` in CI
Updates never arrive	Device on a channel without the bundle, or bundle incompatible with native version; check channel and `npx @capgo/cli@latest bundle compatibility`
Old Appflow update overwrote Capgo bundle	Old SDK still installed in the binary; confirm `@capacitor/live-updates` / `cordova-plugin-ionic` removed and `npx cap sync` run before building
Build fails after removing Appflow	Appflow injected env vars or native config; recreate them in CI or Capgo Cloud Build environment

FAQ

What does the ionic-appflow-migration skill do?

How do I install ionic-appflow-migration?

Run npx skills add https://github.com/cap-go/capgo-skills --skill ionic-appflow-migration in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ionic-appflow-migration/ (personal) or .claude/skills/ionic-appflow-migration/ (project).

Which AI agents can use ionic-appflow-migration?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is ionic-appflow-migration safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains ionic-appflow-migration?

It is published by cap-go in cap-go/capgo-skills. It has 654 recorded installs.

More from cap-go/capgo-skills

View all →

capacitor-best-practices

cap-go/capgo-skills

Review and set up Capacitor apps against current best practices (Capacitor 8.5 stable, 9 alpha via @next). Use for a Capacitor codebase review, capacitor.config.ts audit, new project setup, aligning @capacitor/core/cli/ios/android and plugin majors, plugin patterns (availability checks, checkPermissions/requestPermissions, error code handling, web fallbacks), or release prep; or on " " plugin is not implemented on ios, Could not find the web assets directory, platform has not been added yet, a dev server.url shipped to production, lost edits in android/app/src/main/assets/public, SPM vs CocoaPods, or AppDelegate/UIScene drift. Do not use for security audits (capacitor-security), performance (capacitor-performance), tests (capacitor-testing), crashes (debugging-capacitor), major upgrades (capacitor-app-upgrades), SPM migration (cocoapods-to-spm), UIScene adoption (capacitor-uiscene-migration), or live updates (capgo-live-updates).

Code Quality & Workflow2.7K installs

ionic-design

cap-go/capgo-skills

Builds and reviews Ionic Framework UI in Capacitor apps (Ionic 9 current, Ionic 8 still common) - page structure (ion-header/ion-content/ion-footer), lists, modern form syntax (label/labelPlacement on ion-input/ion-select), sheet modals, tabs + ion-router-outlet, CSS variable theming, dark palettes (palettes/dark.system.css, .ion-palette-dark), iOS vs MD mode, and Ionic 8 - 9 breaking changes (React Router 6, Vue Router 5, Angular 18-22 zoneless, removed ion-picker-legacy, boolean autocorrect, npx @ionic/migrate). Use when writing Ionic components, theming an Ionic app, fixing platform-mode styling, or upgrading @ionic/react, @ionic/vue, @ionic/angular. Do not use for Konsta UI (konsta-ui), Tailwind setup (tailwind-capacitor), raw safe-area CSS (safe-area-handling), keyboard resize (capacitor-keyboard), or Ionic Appflow/Enterprise migrations (ionic-appflow-migration, ionic-enterprise-sdk-migration).

Frontend & Design1.6K installs

capacitor-plugins

cap-go/capgo-skills

Pick, install, and wire up Capacitor plugins for native features (camera, filesystem, geolocation, biometrics, in-app purchases, social login, SQLite, calendar, contacts, health, BLE, NFC, etc.). Covers official @capacitor/ packages (Capacitor 8.5 stable, 9 alpha on next) plus the 145-package @capgo/ index, native permission keys (Info.plist, AndroidManifest, variables.gradle minSdk), npx cap sync / cap ls verification, and errors like '"Camera" plugin is not implemented on ios', 'unable to find plugin', UNIMPLEMENTED, and OS-PLUG- codes. Use for "which plugin should I use for X", adding a plugin, or a plugin call failing after install. Do not use for push setup (capacitor-push-notifications), splash assets (capacitor-splash-screen), keyboard layout (capacitor-keyboard), deep links (capacitor-deep-linking), OTA updates (capgo-live-updates), upgrading plugin source code (capacitor-plugin-upgrades), or adding SPM to a plugin (capacitor-plugin-spm-support).

Frontend & Design1.6K installs

debugging-capacitor

cap-go/capgo-skills

Diagnoses and fixes runtime bugs in Capacitor iOS/Android apps - white/blank screen on launch, startup crashes, "X" plugin is not implemented on ios/android, net::ERRCLEARTEXTNOTPERMITTED, App Transport Security blocks, CORS on capacitor://localhost, permission denials, live reload not connecting, and Capacitor 8.5+ UIScene regressions (appUrlOpen, universal links, pause/resume silent because AppDelegate callbacks stopped). Covers Safari Web Inspector, chrome://inspect, Xcode/LLDB, Android Studio, npx cap run --url (Capacitor 9) vs -l --host (8), xcrun simctl openurlprivacypush, xcrun devicectl device process launchopenURL, xctrace. Do not use for only reading device logs (ios-android-logs), the UIScene migration itself (capacitor-uiscene-migration), deep-link setup (capacitor-deep-linking), speed (capacitor-performance), crash SDKs (capacitor-native-observability), tests (capacitor-testing), or upgrades/build errors (capacitor-app-upgrades, cocoapods-to-spm).

Code Quality & Workflow1.3K installs

capacitor-testing

cap-go/capgo-skills

Testing guide for Capacitor apps and plugins. Covers web-layer unit and component tests with Vitest and mocked Capacitor plugins (vi.mock('@capacitor/core'), registerPlugin), Playwright for the web build, Appium E2E with NATIVEAPP / WEBVIEW context switching, native plugin unit tests with Swift Testing vs XCTest (what can migrate, CAPPluginCall patterns, xcodebuild test on a simulator) and Android JUnit, plus an agent-driven verification loop on simulators and devices (build, install, launch, screenshot, UI hierarchy, tap, logs) with xcrun simctl, xcrun devicectl, adb, Xcode MCP device tools, and live reload via npx cap run --url (Capacitor 9) or -l --host --port (Capacitor 8). Use when adding tests, mocking plugins, "does it work on device", verifying a UI change on a simulator, migrating XCTest to Swift Testing, or setting up test CI. Do not use for crash log capture (ios-android-logs), WebView debugging sessions (debugging-capacitor), or build pipelines (capacitor

Testing & QA1.3K installs

safe-area-handling

cap-go/capgo-skills

Fixes notch, Dynamic Island, home indicator, display cutout, and system bar overlap in Capacitor apps. Covers viewport-fit=cover + env(safe-area-inset-), the Capacitor 8 SystemBars core plugin (insetsHandling, injected --safe-area-inset- CSS variables for Android WebView < 140, removal of android.adjustMarginsForEdgeToEdge), Android 15/16 enforced edge-to-edge (overlaysWebView and backgroundColor of @capacitor/status-bar no longer work at targetSdk 36), iOS contentInset, and insets that change at runtime on rotation, iPad/foldable resizable windows. Use when headers sit under the status bar, tab bars hide behind the gesture bar, env() returns 0 on Android, or layout broke after upgrading to Capacitor 8 / targetSdk 35+. Do not use for keyboard overlap (capacitor-keyboard), Ionic/Konsta component theming (ionic-design, konsta-ui), Tailwind utility setup (tailwind-capacitor), or iOS multi-window/resizability adoption (capacitor-ios-resizability).

Mobile1.3K installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs

ionic-appflow-migration

Install

Install

Describe the task

Review the result

SKILL.md

Ionic Appflow Migration

When to Use

Live Project Snapshot

Procedure

Step 1: Inventory (report before editing)

Step 2: Live Updates -> Capgo

Step 3: Native cloud builds

Step 4: Store publishing

Step 5: Cut over and clean up

Verification

Error Handling

FAQ

More from cap-go/capgo-skills

Popular code quality & workflow skills