Capacitor App Upgrade

When to Use This Skill

• User wants to move a Capacitor app from one major version to another
• User is preparing for a multi-version jump
• User needs a safe fallback when automated migration does not complete cleanly

Live Project Snapshot

package.json

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('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"

find . -maxdepth 3 \( -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' -o -path './ios' -o -path './android' \)

Procedures

Step 1: Detect the Current Version

@capacitor/core

package.json

Step 2: Upgrade One Major Version at a Time

1. Update the

   @capacitor/*

   package versions in

   package.json

   .
2. Run

   npm install

   .
3. Run the Capacitor migration flow if available for that version.
4. Sync native projects with

   npx cap sync

   .
5. Verify iOS and Android build cleanly before continuing.

Step 3: Check Native Projects

• iOS deployment target
• Xcode compatibility
• Android Gradle Plugin and Java version
• Any plugin-specific native changes introduced by the new Capacitor major version

Step 4: Final Verification

npm install
npx cap sync
npx cap run ios
npx cap run android

Error Handling

• If the automated migration step only partially completes, finish the current major version manually before trying the next one.
• If iOS fails, verify the deployment target and Xcode version match the target Capacitor major version.
• If Android fails, verify the Gradle and Java requirements for the target version.
• If the app uses plugins with their own upgrade constraints, handle those plugins separately after the app version is stable.