ionic-enterprise-sdk-migration
Migrates Capacitor apps off Ionic Enterprise SDK plugins - @ionic-enterprise/auth (Auth Connect), @ionic-enterprise/identity-vault (Identity Vault), and @ionic-enterprise/secure-storage (Secure Storage) - to @capgo/capacitor-social-login (OAuth2/OIDC for Azure AD, Auth0, Okta, Cognito, plus Google/Apple), @capgo/capacitor-native-biometric (biometric-protected Keychain/Keystore credential vault), and @capgo/capacitor-fast-sql or @capgo/capacitor-data-storage-sqlite (encrypted storage). Use when package.json has @ionic-enterprise/ packages, code imports AuthConnect, BrowserVault/Vault/DeviceSecurityType, or SQLite from secure-storage, or the user needs to move stored tokens without logging users out. Do not use for Ionic Appflow live updates or builds (ionic-appflow-migration), generic SQLite plugin swaps (sqlite-to-fast-sql), Capacitor version upgrades (capacitor-app-upgrades), or Capgo live updates (capgo-live-updates).
- Installs
- 685
- 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-enterprise-sdk-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-enterprise-sdk-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 Enterprise SDK Migration
Replace Ionic Enterprise plugins with open Capgo plugins one at a time, preserving login sessions and stored data.
Context: Ionic stopped selling its commercial products (including the Enterprise SDK) in February 2025 and is winding down maintenance; plan migrations before the license or support window ends.
When to Use
TRIGGER when:
package.jsoncontains@ionic-enterprise/auth,@ionic-enterprise/identity-vault, or@ionic-enterprise/secure-storage.- Code imports
AuthConnect,ProviderOptions,Vault,BrowserVault,VaultType,DeviceSecurityType, or Secure Storage'sSQLite/KeyValueStorage. - The user asks how to replace Auth Connect, Identity Vault, or Secure Storage without forcing re-login.
Do not use for:
- Appflow Live Updates / builds ->
ionic-appflow-migration. - Community or other SQLite plugins ->
sqlite-to-fast-sql. - Biometric UX or general security review ->
capacitor-security.
Live Project Snapshot
Detected Ionic Enterprise and replacement 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('@ionic-enterprise/')||name.startsWith('@capgo/')||name==='@capacitor/preferences'||name==='@capacitor/core')out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"
Replacement Map
| Ionic Enterprise | Replacement | Covers | Not covered (rebuild in app) |
|---|---|---|---|
| Auth Connect | @capgo/capacitor-social-login (provider: 'oauth2' for OIDC/OAuth2 IdPs; google, apple, facebook, etc.) | Authorization code + PKCE, token refresh (refreshToken), logout, native Apple/Google sign-in | Token storage policy (store tokens with Native Biometric or encrypted SQL) |
| Identity Vault | @capgo/capacitor-native-biometric | Save/read/delete credentials in Keychain/Keystore; accessControl: BIOMETRY_CURRENT_SET or BIOMETRY_ANY makes reads require biometrics; verifyIdentity with passcode fallback on iOS; biometryChange listener | Inactivity lock timeout, privacy screen on background (@capacitor/privacy-screen), custom-passcode vaults, in-memory vaults |
| Secure Storage (SQLite) | @capgo/capacitor-fast-sql with encrypted: true + encryptionKey | Encrypted SQLite (SQLCipher), transactions, batch, KeyValueStore | Key management - keep the DB key in Native Biometric, not in JS constants |
| Secure Storage (key-value) | @capgo/capacitor-data-storage-sqlite or Fast SQL KeyValueStore | Simple encrypted key-value |
Non-sensitive settings can go to @capacitor/preferences. Never move tokens or secrets there.
Procedure
Step 1: Detect and plan
rg -n "@ionic-enterprise/" -g '!node_modules' .
List each enterprise package, every call site, and what is stored (keys, DB names, vault config: type, deviceSecurityType, lockAfterBackgrounded, unlockVaultOnLoad). Migrate one plugin per release when more than one is present. Report the plan before editing.
Step 2: Plan data carry-over (two-release rule)
Old plugin data can only be read while the old plugin is still installed. For tokens, vault values, or encrypted DBs:
- Release N: install the Capgo replacement alongside the enterprise plugin. On first launch, read from the old store, write to the new one, set a
migratedflag, then clear the old store. - Release N+1 (after most users have opened release N): remove the enterprise plugin.
If the user accepts a forced re-login for everyone, a single release is fine; confirm this explicitly.
Step 3: Auth Connect -> Social Login
npm install @capgo/capacitor-social-login
npx cap sync
- Keep the same client IDs, scopes, and redirect URIs; register any new native redirect (custom scheme or universal link) with the IdP before shipping.
- Map each Auth Connect provider (Azure, Auth0, Okta, Cognito, generic OIDC) to an
oauth2entry inSocialLogin.initialize({ oauth2: { <providerId>: { ... } } })withclientId/appId,issuerUrlorauthorizationBaseUrl+accessTokenEndpoint,redirectUrl, and scopes. Check the plugin's OAuth2 docs for the exact fields of the installed version. - Replace
AuthConnect.login/logout/refreshSession/isAccessTokenExpiredwithSocialLogin.login({ provider: 'oauth2', options: { providerId } }),logout,refreshToken, and your own expiry check on the returned token. - Compare the before/after authorization request (scopes,
prompt, audience) and token response in a test tenant.
Step 4: Identity Vault -> Native Biometric
npm install @capgo/capacitor-native-biometric
npx cap sync
import { NativeBiometric, AccessControl } from '@capgo/capacitor-native-biometric';
await NativeBiometric.setCredentials({
server: 'com.company.app.session',
username: userId,
password: refreshToken,
accessControl: AccessControl.BIOMETRY_CURRENT_SET,
});
const { password: token } = await NativeBiometric.getSecureCredentials({
server: 'com.company.app.session',
reason: 'Unlock your account',
});
lockAfterBackgrounded-> onAppresume, if elapsed time exceeds the timeout, show a lock screen and callgetSecureCredentialsagain.DeviceSecurityType.Both/ passcode fallback ->verifyIdentitysupports device passcode fallback on iOS; protected credential reads stay biometric-only.BIOMETRY_CURRENT_SETinvalidates the item when biometrics change (like Identity Vault's strict mode);BIOMETRY_ANYsurvives enrollment changes.- Privacy screen in app switcher ->
@capacitor/privacy-screen. - iOS: add
NSFaceIDUsageDescriptiontoInfo.plist.
Step 5: Secure Storage -> Fast SQL or Data Storage SQLite
npm install @capgo/capacitor-fast-sql
npx cap sync
import { FastSQL, KeyValueStore } from '@capgo/capacitor-fast-sql';
const db = await FastSQL.connect({ database: 'app', encrypted: true, encryptionKey });
const kv = await KeyValueStore.open({ database: 'kv', encrypted: true, encryptionKey });
- Keep the same schema; port queries (
executeSql->db.query/db.run/db.executeBatch/db.transaction). - Encryption requires SQLCipher: Android
implementation 'net.zetetic:sqlcipher-android:<version>'inandroid/app/build.gradle; iOS CocoaPods subspecCapgoCapacitorFastSql/SQLCipher. Without it,encrypted: truefails withEncryption is not available in this buildon iOS. - Fast SQL runs a localhost HTTP server: add
NSAppTransportSecurity->NSAllowsLocalNetworking(iOS) and a localhost cleartextnetwork_security_config.xml(Android). Seesqlite-to-fast-sqlfor the full setup. - Store
encryptionKeywith Native Biometric (Step 4) or derive it server-side; never hard-code it.
Step 6: Clean up
npm uninstall @ionic-enterprise/auth @ionic-enterprise/identity-vault @ionic-enterprise/secure-storage
rg -n "@ionic-enterprise" -g '!node_modules' .
npx cap sync
Remove the Ionic Enterprise registry/token lines from .npmrc only after no enterprise package remains (CI installs fail otherwise).
Verification
- Upgrade test: install the current store build, log in, store data; install the new build over it; user stays logged in and data is present.
- Fresh install: login, token refresh, logout, and biometric unlock work on real iOS and Android devices (simulators cannot fully test biometrics).
- Change device biometrics:
BIOMETRY_CURRENT_SETitems become unreadable and the app falls back to login. rg -n "@ionic-enterprise" -g '!node_modules' .returns nothing after the final release.npm cisucceeds in CI without Ionic Enterprise registry credentials.
Error Handling
| Problem | Fix |
|---|---|
npm error 401 Unauthorized / 404 for @ionic-enterprise/* in CI | Enterprise registry token expired; finish removal or keep the token until release N+1 |
| Users logged out after update | Data not carried over; ship the dual-plugin release N first |
redirect_uri_mismatch / IdP error after switching | Register the new redirect URL with the IdP; keep scopes identical |
Encryption is not available in this build | Add the SQLCipher dependency/subspec, rebuild |
| Fast SQL calls fail with network errors | Missing ATS local networking / Android cleartext config for localhost |
| Biometric read fails after enrollment change | Expected with BIOMETRY_CURRENT_SET; re-authenticate and save again |
FAQ
What does the ionic-enterprise-sdk-migration skill do?
Migrates Capacitor apps off Ionic Enterprise SDK plugins - @ionic-enterprise/auth (Auth Connect), @ionic-enterprise/identity-vault (Identity Vault), and @ionic-enterprise/secure-storage (Secure Storage) - to @capgo/capacitor-social-login (OAuth2/OIDC for Azure AD, Auth0, Okta, Cognito, plus Google/Apple), @capgo/capacitor-native-biometric (biometric-protected Keychain/Keystore credential vault), and @capgo/capacitor-fast-sql or @capgo/capacitor-data-storage-sqlite (encrypted storage). Use when package.json has @ionic-enterprise/ packages, code imports AuthConnect, BrowserVault/Vault/DeviceSecurityType, or SQLite from secure-storage, or the user needs to move stored tokens without logging users out. Do not use for Ionic Appflow live updates or builds (ionic-appflow-migration), generic SQLite plugin swaps (sqlite-to-fast-sql), Capacitor version upgrades (capacitor-app-upgrades), or Capgo live updates (capgo-live-updates).
How do I install ionic-enterprise-sdk-migration?
Run npx skills add https://github.com/cap-go/capgo-skills --skill ionic-enterprise-sdk-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-enterprise-sdk-migration/ (personal) or .claude/skills/ionic-enterprise-sdk-migration/ (project).
Which AI agents can use ionic-enterprise-sdk-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-enterprise-sdk-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-enterprise-sdk-migration?
It is published by cap-go in cap-go/capgo-skills. It has 685 recorded installs.
More from cap-go/capgo-skills
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).
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).
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).
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).
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
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).
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
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.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
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.
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.
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.