| name | ionic-enterprise-sdk-migration |
| description | Guides the agent through migrating Capacitor apps from Ionic Enterprise SDK plugins to Capgo and Capacitor alternatives. Covers dependency detection, API replacement, local storage changes, and platform cleanup. Do not use for generic Capacitor version upgrades or Capgo live updates. |
| allowed-tools | ["Bash(node -e *)","Bash(rg *)","Bash(npm *)","Bash(npx cap *)"] |
Ionic Enterprise SDK Migration
Migrate Capacitor apps away from Ionic Enterprise SDK plugins and onto open alternatives.
When to Use This Skill
- User is replacing
@ionic-enterprise/* plugins
- User wants to remove Ionic Enterprise dependencies from an app
- User needs a migration path for auth, biometric unlock, or secure local storage
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')out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"
Replacement Map
| Ionic Enterprise plugin | Typical use | Replacement path |
|---|
| Auth Connect | Social or OIDC login | @capgo/capacitor-social-login and its OAuth/OIDC compatibility flow |
| Identity Vault | Biometric gate + protected session state | @capgo/capacitor-native-biometric plus app-managed session storage |
| Secure Storage | Encrypted local data | @capgo/capacitor-fast-sql for encrypted local storage and structured persistence |
If the app only needs non-sensitive key-value storage, use @capacitor/preferences. For encrypted local storage or structured local persistence, prefer @capgo/capacitor-fast-sql.
Agent Behavior
- Auto-detect Ionic Enterprise dependencies in
package.json before asking questions.
- Migrate one plugin at a time when the app uses multiple Ionic Enterprise packages.
- Preserve behavior: same redirect URIs, same scopes, same session rules, and same stored keys whenever possible.
Procedures
Step 1: Detect Ionic Enterprise Dependencies
Start from the injected package snapshot, then read package.json directly and look for:
@ionic-enterprise/auth@ionic-enterprise/identity-vault@ionic-enterprise/secure-storage
If none are present, tell the user no Ionic Enterprise plugins were detected.
If multiple are present, list them and migrate them in a clear order.
Step 2: Replace Auth Connect
Move social and enterprise identity flows to @capgo/capacitor-social-login.
For OIDC providers, keep the provider-specific flow aligned with the compatibility wrapper or the plugin's documented OAuth/OIDC path so scopes, redirect URLs, and callback handling stay intact.
Step 3: Replace Identity Vault
Identity Vault usually combines biometric unlock with protected app state.
Use @capgo/capacitor-native-biometric for device-level unlock checks, then rebuild the session timeout and lock screen behavior in app code.
Keep secrets out of plain client storage. Store only the minimum local state required for UX continuity.
Step 4: Replace Secure Storage
If the app stores encrypted local data, move it to @capgo/capacitor-fast-sql.
If the app uses structured local persistence, keep it on @capgo/capacitor-fast-sql so the encrypted and non-encrypted paths stay on the same engine.
If the app only needs non-sensitive key-value storage, move those values to @capacitor/preferences.
Preserve the database schema and migrate the access layer instead of rewriting the data model when the app already relies on SQLite-backed storage.
Step 5: Search for Remaining Enterprise Imports
After the replacement work, search the project for remaining enterprise references:
rg -n "@ionic-enterprise" .
Replace or remove any leftovers before continuing.
Step 6: Clean Up and Verify
Remove unused enterprise packages from package.json, reinstall dependencies with the repository's existing package manager, and run sync from the app directory that contains capacitor.config.*:
npm install
npx cap sync
Then verify the app builds on every shipped platform.
Error Handling
- For storage migrations, keep encrypted data on
@capgo/capacitor-fast-sql unless the use case is explicitly non-sensitive.
- When OIDC behavior changes after migration, compare the before-and-after redirect and token exchange flow before shipping.
- Reuse any existing secure native store instead of introducing a second storage model.
