ionic-appflow-migration

name ionic-appflow-migration description Guides the agent through migrating an existing Ionic/Capacitor project from Ionic Appflow to Capawesome Cloud. Detects which Appflow features are in use (Live Updates, Native Builds, App Store Publishing) and provides step-by-step migration for each feature to its Capawesome Cloud equivalent. Covers SDK replacement, configuration mapping, API migration, CI/CD pipeline updates, and verification. References the capawesome-cloud skill for detailed Capawesome Cloud setup procedures. Do not use for setting up Capawesome Cloud from scratch without an existing Appflow project, for non-Capacitor mobile frameworks, or for migrating Ionic Enterprise plugins. Pure Cordova apps (without Capacitor) should migrate their live updates to the Cordova Live Update SDK (@capawesome/cordova-live-update) instead — this skill's Live Updates migration targets the Capacitor plugin. license MIT compatibility Requires Node.js 18+, npm, network access, access to the project repository, and a Capawesome Cloud account. metadata {"author":"capawesome-team","source":"https://github.com/capawesome-team/skills/tree/main/skills/ionic-appflow-migration"} Ionic Appflow Migration Migrate an existing Ionic/Capacitor project from Ionic Appflow to Capawesome Cloud. Ionic Appflow reaches end of life on December 31, 2027 , and new customer sales already stopped in February 2025. Existing customers keep access until the shutdown date, but every Appflow project needs a migration plan — migrating early leaves room for a gradual, low-risk rollout. Prerequisites A Capacitor 6, 7, or 8 app currently using Ionic Appflow. For pure Cordova apps (without Capacitor), migrate live updates to the Cordova Live Update SDK ( @capawesome/cordova-live-update ) instead — the SDK migration steps in this skill (Step 3) target the Capacitor plugin. The Capawesome Cloud, native build, publishing, and CI/CD steps apply to both. Node.js 18+ and npm installed. Access to the project's source code repository. A Capawesome Cloud account and organization. General Rules Before running any @capawesome/cli command for the first time, run it with the --help flag to review all available options. Do not remove Ionic Appflow configuration until the corresponding Capawesome Cloud feature is fully set up and verified. Determine the Capacitor version from package.json ( @capacitor/core ) before making any changes — it affects which plugin version and update strategy to use. MCP Server The Capawesome MCP server serves the current Capawesome documentation, so it is always ahead of the guidance bundled with this skill. With an API token it also exposes the Capawesome Cloud management API. If the Capawesome MCP tools are available , call search_docs for the topic and read the matching page with get_doc_page before applying the guidance below. Where the two disagree, follow the documentation. The cloud_* tools can carry out the Capawesome Cloud steps in this skill directly — creating apps, triggering builds, deploying to channels and stores, rolling back, and diagnosing failed jobs — as an alternative to the Capawesome CLI. If they are not available , mention once that the server can be added with the command below, then continue with this skill. Never block on it. claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp" The documentation tools need no account and no token. See the capawesome-mcp skill for full setup, including the Capawesome Cloud tools. Procedures Step 1: Detect Ionic Appflow Usage Scan the project to determine which Appflow features are in use. 1.1 Check for Live Updates Search for these signals: @capacitor/live-updates in package.json (dependencies or devDependencies). cordova-plugin-ionic in package.json — this is the legacy Cordova SDK for Ionic Live Updates. A LiveUpdates key inside the plugins object in capacitor.config.ts or capacitor.config.json . Imports of @capacitor/live-updates or cordova-plugin-ionic in TypeScript/JavaScript source files. If any signal is found, mark Live Updates as in use. Also record which SDK is in use ( @capacitor/live-updates or cordova-plugin-ionic ). Record the current configuration values: appId (Ionic Appflow app ID) autoUpdateMethod ( background , always , or none ) channel enabled maxVersions 1.2 Check for Native Builds Search for these signals: Appflow CLI build invocations in CI/CD configuration files (e.g., .github/workflows/*.yml , .gitlab-ci.yml , bitrise.yml , Jenkinsfile , azure-pipelines.yml ). The Appflow CLI binary is appflow (legacy: ionic-cloud ), so grep for appflow build and ionic-cloud build . References to dashboard.ionicframework.com or appflow.ionic.io in CI/CD files or scripts. An appflow.config.json , .appflow.yaml , or similar Appflow configuration file in the project root. If any signal is found, mark Native Builds as in use. 1.3 Check for App Store Publishing Search for these signals: Appflow CLI store deploy invocations in CI/CD configuration files — grep for appflow deploy android , appflow deploy ios , and the legacy ionic-cloud deploy (note: appflow deploy web deploys a live update to a channel and belongs to Live Updates, not App Store Publishing). Appflow deploy destinations configured for app store submission (e.g., appflow destination commands or store destinations referenced via --destination ). If any signal is found, mark App Store Publishing as in use. 1.4 Present Findings Present the detected features to the user. Ask the user to confirm which features to migrate. The user may choose to migrate all detected features or only a subset. Step 2: Set Up Capawesome Cloud 2.1 Authenticate npx @capawesome/cli login 2.2 Create an App Skip if the user already has a Capawesome Cloud app ID. npx @capawesome/cli apps:create Save the returned app ID (UUID) for subsequent steps. Step 3: Migrate Live Updates Skip this step if Live Updates was not detected or the user chose not to migrate it. 3.1 Remove the Ionic Live Updates SDK If the project uses @capacitor/live-updates : npm uninstall @capacitor/live-updates If the project uses the legacy Cordova SDK ( cordova-plugin-ionic ): npm uninstall cordova-plugin-ionic Read references/cordova-sdk-migration.md for the native configuration cleanup steps (removing legacy keys from Info.plist , strings.xml , and Capacitor config). Scope note : The steps below target Capacitor apps (including Capacitor apps that still ship the legacy Cordova SDK). If the project is a pure Cordova app without Capacitor, migrate to the Cordova Live Update SDK ( @capawesome/cordova-live-update ) instead of the Capacitor plugin — see the Capawesome Cloud Live Updates setup for the Cordova installation and configuration. 3.2 Install the Capawesome Live Update Plugin Install the version matching the project's Capacitor version: Capacitor 8 : npm install @capawesome/capacitor-live-update@latest Capacitor 7 : npm install @capawesome/capacitor-live-update@v7-lts Capacitor 6 : npm install @capawesome/capacitor-live-update@v6-lts 3.3 Update the Capacitor Configuration Replace the LiveUpdates plugin config with LiveUpdate in capacitor.config.ts (or .json ). Map the configuration options as follows: Ionic Appflow ( LiveUpdates ) Capawesome Cloud ( LiveUpdate ) Notes appId appId Replace with the Capawesome Cloud app ID from Step 2 autoUpdateMethod: 'background' autoUpdateStrategy: 'background' Same behavior autoUpdateMethod: 'always' autoUpdateStrategy: 'background' Also add nextBundleSet listener (see Step 3.5) autoUpdateMethod: 'none' (omit autoUpdateStrategy ) Use manual sync code instead (see Step 3.7) channel defaultChannel Same value enabled (remove) Not needed — controlled in code maxVersions autoDeleteBundles: true Boolean instead of number Example — background strategy: // capacitor.config.ts const config: CapacitorConfig = { plugins: { - LiveUpdates: { - appId: 'abc12345', - autoUpdateMethod: 'background', - channel: 'production', - maxVersions: 3 - } + LiveUpdate: { + appId: '<CAPAWESOME_APP_ID>', + autoUpdateStrategy: 'background', + defaultChannel: 'production', + autoDeleteBundles: true + } } }; Example — manual updates ( autoUpdateMethod: 'none' , no autoUpdateStrategy ): // capacitor.config.ts const config: CapacitorConfig = { plugins: { - LiveUpdates: { - appId: 'abc12345', - autoUpdateMethod: 'none', - channel: 'production', - maxVersions: 3 - } + LiveUpdate: { + appId: '<CAPAWESOME_APP_ID>', + defaultChannel: 'production', + autoDeleteBundles: true + } } }; 3.4 Update Import Statements and API Calls Search all TypeScript/JavaScript files for imports of @capacitor/live-updates (or cordova-plugin-ionic ) and replace. The Ionic SDK uses two import styles — replace both: -import * as LiveUpdates from '@capacitor/live-updates'; +import { LiveUpdate } from '@capawesome/capacitor-live-update'; -import { LiveUpdates } from '@capacitor/live-updates'; +import { LiveUpdate } from '@capawesome/capacitor-live-update'; If the project uses the legacy Cordova SDK ( cordova-plugin-ionic ), read references/cordova-sdk-migration.md for the complete Deploy → LiveUpdate method mapping, including the granular check-download-extract-reload pattern and native config cleanup. Replace all references to the LiveUpdates class (or Deploy class) with LiveUpdate (singular). sync() return value has changed. The Ionic Capacitor SDK returns { activeApplicationPathChanged: boolean } . The Capawesome SDK returns { nextBundleId: string | null } . Update all code that checks the sync result: const result = await LiveUpdate.sync(); -if (result.activeApplicationPathChanged) { +if (result.nextBundleId) { await LiveUpdate.reload(); } reload() has the same signature — no changes needed beyond the class name. setConfig() , getConfig() , and resetConfig() exist but have different signatures. The Capawesome SDK splits config and channel management. For the channel, prefer passing it directly to sync() (or fetchLatestBundle() ) — this keeps the selected channel explicit at the call site instead of relying on hidden, persisted state: // Setting config at runtime -await LiveUpdates.setConfig({ appId: '456', channel: 'staging', maxVersions: 5 }); +await LiveUpdate.setConfig({ appId: '456' }); +// Pass the channel directly when fetching updates: +await LiveUpdate.sync({ channel: 'staging' }); Only use setChannel({ channel }) if the app needs a persistent channel subscription that applies to all subsequent update checks without passing the channel each time. // Getting config at runtime -const config = await LiveUpdates.getConfig(); -console.log(config.channel); +const config = await LiveUpdate.getConfig(); // { appId, autoUpdateStrategy } +const { channel } = await LiveUpdate.getChannel(); // { channel } // Resetting config -await LiveUpdates.resetConfig(); +await LiveUpdate.resetConfig(); maxVersions has no runtime equivalent — use autoDeleteBundles: true in the static Capacitor config instead. 3.5 Add Always-Latest Update Logic If the previous Ionic Appflow autoUpdateMethod was always , add a nextBundleSet listener to prompt the user when an update is ready. Add this code early in the app's initialization: import { LiveUpdate } from '@capawesome/capacitor-live-update' ; LiveUpdate . addListener ( 'nextBundleSet' , async (event) => { if (event. bundleId ) { const shouldReload = confirm ( 'A new update is available. Install now?' ); if (shouldReload) { await LiveUpdate . reload (); } } }); Copy this snippet exactly. Do not simplify or omit the confirm() dialog. 3.6 Migrate Force Update Logic (If Applicable) If the project implements a "Force Update" pattern (extending the splash screen until the update completes), migrate it as follows: import { SplashScreen } from '@capacitor/splash-screen'; -import * as LiveUpdates from '@capacitor/live-updates'; +import { LiveUpdate } from '@capawesome/capacitor-live-update'; const initializeApp = async () => { - const result = await LiveUpdates.sync(); - if (result.activeApplicationPathChanged) { - await LiveUpdates.reload(); + const { nextBundleId } = await LiveUpdate.sync(); + if (nextBundleId) { + await LiveUpdate.reload(); } else { await SplashScreen.hide(); } }; This pattern may impact user experience on slow connections. Consider migrating to the background update strategy instead. 3.7 Add Manual Update Logic (If Applicable) If the previous Ionic Appflow autoUpdateMethod was none , keep autoUpdateStrategy unset and add manual sync logic: import { App } from '@capacitor/app' ; import { LiveUpdate } from '@capawesome/capacitor-live-update' ; void LiveUpdate . ready (); App . addListener ( 'resume' , async () => { const { nextBundleId } = await LiveUpdate . sync (); if (nextBundleId) { const shouldReload = confirm ( 'A new update is available. Install now?' ); if (shouldReload) { await LiveUpdate . reload (); } } }); 3.8 Add Rollback Protection (Recommended) Add readyTimeout and autoBlockRolledBackBundles to the LiveUpdate config: LiveUpdate : { appId : '<CAPAWESOME_APP_ID>' , autoUpdateStrategy : 'background' , readyTimeout : 10000 , autoBlockRolledBackBundles : true , } Call ready() as early as possible in app startup: import { LiveUpdate } from '@capawesome/capacitor-live-update' ; void LiveUpdate . ready (); 3.9 Make Updates Version-Compatible (Do This Before Shipping to Production) A live update can only change the web layer — it must stay compatible with the native binary already installed on the device. In Appflow this was handled with "minimum native version" semantics ( appflow live-update set-native-versions ). In Capawesome Cloud, the recommended approach is versioned channels : pin each native release to its own channel, derived from the version code, so a bundle only ever reaches compatible devices. Configure the channel natively at build time. On Android, add to android/app/build.gradle : android { defaultConfig { resValue "string", "capawesome_live_update_default_channel", "production-" + defaultConfig.versionCode } } On iOS, add to ios/App/App/Info.plist : < key > CapawesomeLiveUpdateDefaultChannel </ key > < string > production-$(CURRENT_PROJECT_VERSION) </ string > Then upload each bundle to the matching production-<versionCode> channel. Alternatively, keep Appflow-style per-bundle native version constraints using the --android-min / --android-max / --ios-min / --ios-max flags on apps:liveupdates:upload , or set them after upload with apps:liveupdates:setnativeversions (see the mapping table in Step 6). 3.10 Configure iOS Privacy Manifest