Cordova to Capacitor Migration

Step-by-step guide for migrating from Apache Cordova/PhoneGap to Capacitor.

When to Use This Skill

• Migrating an existing Cordova app to Capacitor
• Converting PhoneGap projects to Capacitor
• Understanding Cordova vs Capacitor differences
• Finding Capacitor equivalents for Cordova plugins
• Modernizing hybrid mobile apps

Why Migrate from Cordova?

Migration Process Overview

Step 1: Assess Your Current App

Check Cordova version:

cordova --version
cordova platform version

List installed plugins:

cordova plugin list

Review config.xml:

cat config.xml

Step 2: Install Capacitor

In your existing Cordova project:

# Install Capacitor
bun add @capacitor/core @capacitor/cli

# Initialize Capacitor
bunx cap init

When prompted:

• App name: Your app's display name
• App ID: Use the same ID from config.xml (e.g., com.company.app)
• Web directory: Usually www for Cordova projects

Step 3: Add Platforms

Capacitor doesn't modify web assets. Add platforms separately:

# Add iOS platform
bun add @capacitor/ios
bunx cap add ios

# Add Android platform
bun add @capacitor/android
bunx cap add android

This creates:

• ios/ directory with Xcode project
• android/ directory with Android Studio project

Step 4: Migrate Plugins

CRITICAL: Check plugin compatibility first.

Core Cordova Plugins → Capacitor Equivalents

Third-Party Cordova Plugins → Capgo Equivalents

For biometrics:

# Cordova
cordova plugin add cordova-plugin-fingerprint-aio

# Capacitor
bun add @capgo/capacitor-native-biometric

For payments:

# Cordova
cordova plugin add cordova-plugin-purchase

# Capacitor
bun add @capgo/capacitor-purchases

For social login:

# Facebook
bun add @capgo/capacitor-social-login

# Google
bun add @codetrix-studio/capacitor-google-auth

Check the full plugin catalog: https://github.com/Cap-go/awesome-capacitor

Step 5: Update Code

Import Changes

Cordova (old):

document.addEventListener('deviceready', () => {
  navigator.camera.getPicture(success, error, options);
});

Capacitor (new):

import { Camera } from '@capacitor/camera';

// No deviceready event needed
const image = await Camera.getPhoto({
  quality: 90,
  allowEditing: true,
  resultType: CameraResultType.Uri
});

Common Pattern Changes

Device Information:

// Cordova
const uuid = device.uuid;
const platform = device.platform;

// Capacitor
import { Device } from '@capacitor/device';
const info = await Device.getId();
const platform = await Device.getInfo();

Network Status:

// Cordova
const networkState = navigator.connection.type;

// Capacitor
import { Network } from '@capacitor/network';
const status = await Network.getStatus();
console.log('Connected:', status.connected);

Geolocation:

// Cordova
navigator.geolocation.getCurrentPosition(success, error);

// Capacitor
import { Geolocation } from '@capacitor/geolocation';
const position = await Geolocation.getCurrentPosition();

Remove deviceready Event

Capacitor doesn't need deviceready. Plugins work immediately.

// Cordova (remove this)
document.addEventListener('deviceready', onDeviceReady, false);

function onDeviceReady() {
  // Your code
}

// Capacitor (just use directly)
import { Camera } from '@capacitor/camera';

async function takePicture() {
  const photo = await Camera.getPhoto();
}

Step 6: Update Configuration

Cordova uses config.xml. Capacitor uses capacitor.config.ts

Create capacitor.config.ts

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.company.app', // From config.xml widget id
  appName: 'My App',         // From config.xml name
  webDir: 'www',             // From Cordova build output
  server: {
    androidScheme: 'https'
  },
  plugins: {
    SplashScreen: {
      launchShowDuration: 3000,
      backgroundColor: '#ffffff',
      androidScaleType: 'CENTER_CROP',
      showSpinner: false
    }
  }
};

export default config;

Migrate config.xml Settings

Preferences:

<!-- Cordova config.xml -->
<preference name="Orientation" value="portrait" />
<preference name="StatusBarOverlaysWebView" value="false" />
<preference name="StatusBarBackgroundColor" value="#000000" />

Capacitor equivalent:

• Orientation: Set in Xcode/Android Studio per platform
• StatusBar: Use @capacitor/status-bar plugin

Platform-specific config:

<!-- Cordova config.xml -->
<platform name="ios">
  <allow-intent href="itms:*" />
</platform>

Capacitor equivalent:

// capacitor.config.ts
const config: CapacitorConfig = {
  ios: {
    contentInset: 'always',
  },
  android: {
    allowMixedContent: true,
  }
};

Step 7: Handle Permissions

Capacitor requires explicit permission configuration.

iOS: Info.plist

Add to ios/App/App/Info.plist:

<key>NSCameraUsageDescription</key>
<string>We need camera access to take photos</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>We need photo library access to select images</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need location to show nearby places</string>

<key>NSMicrophoneUsageDescription</key>
<string>We need microphone access for audio recording</string>

Android: AndroidManifest.xml

Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />

Step 8: Sync and Build

Sync web code with native projects:

bunx cap sync

This copies:

• Web assets from www/ to native projects
• Installs native dependencies
• Updates plugin configurations

Build for iOS:

bunx cap open ios
# Then build in Xcode (Cmd+R)

Build for Android:

bunx cap open android
# Then build in Android Studio (Run)

Step 9: Test the App

Test all plugin functionality:

• Camera/photo picker
• Geolocation
• File operations
• Network detection
• Device information
• Push notifications

Check for:

• Missing permissions
• API differences
• Callback → Promise conversions
• Removed plugins

Step 10: Remove Cordova

Once migration is complete and tested:

# Remove Cordova platforms
cordova platform remove ios
cordova platform remove android

# Remove Cordova
bun remove cordova
bun remove cordova-ios
bun remove cordova-android

# Remove Cordova plugins
cordova plugin list | xargs -I {} cordova plugin remove {}

# Remove config.xml (after backing up)
mv config.xml config.xml.backup

Common Issues and Solutions

Issue: Plugin Not Found

Problem:

Error: Plugin not found

Solution:

1. Check if plugin is installed: bun list
2. Sync native projects: bunx cap sync
3. Clean and rebuild in Xcode/Android Studio

Issue: deviceready Never Fires

Problem: Cordova's deviceready event doesn't exist in Capacitor.

Solution: Remove all deviceready event listeners. Capacitor plugins work immediately.

// Remove this
document.addEventListener('deviceready', onDeviceReady);

// Use this
import { App } from '@capacitor/app';
App.addListener('appStateChange', (state) => {
  console.log('App state changed:', state.isActive);
});

Issue: White Screen on Startup

Problem: App shows white screen or crashes.

Solution:

1. Check webDir in capacitor.config.ts points to correct build output
2. Rebuild web app: bun run build
3. Sync: bunx cap sync
4. Check browser console in device for errors

Issue: Permissions Not Working

Problem: Camera/location/etc. fail silently.

Solution:

1. Add permission strings to Info.plist (iOS)
2. Add permission declarations to AndroidManifest.xml (Android)
3. Request permissions explicitly in code:

import { Camera } from '@capacitor/camera';

// Capacitor handles permission prompts automatically
const photo = await Camera.getPhoto();

Issue: Plugins Using Old Cordova API

Problem: Some third-party Cordova plugins still reference Cordova global.

Solution: Use the Capacitor Cordova compatibility layer:

bun add cordova-plugin-example
bunx cap sync

Capacitor includes Cordova compatibility, but:

• It's best to migrate to native Capacitor plugins when possible
• Not all Cordova plugins will work

Hybrid Approach: Run Both

You can run Cordova and Capacitor side-by-side during migration.

1. Install Capacitor alongside Cordova
2. Keep both config.xml and capacitor.config.ts
3. Migrate plugins incrementally
4. Test each platform independently

When ready, remove Cordova entirely.

Plugin Migration Checklist

• List all Cordova plugins: cordova plugin list
• Find Capacitor equivalents (use table above)
• Install Capacitor plugins: bun add @capacitor/plugin-name
• Update imports in code
• Convert callbacks to async/await
• Remove deviceready event listeners
• Add permission strings (iOS Info.plist, Android AndroidManifest.xml)
• Sync native projects: bunx cap sync
• Test on physical devices
• Remove Cordova plugins after verification

Live Updates with Capgo

Capacitor enables instant updates without app store review.

After migration, add Capgo for OTA updates:

# Install Capgo plugin
bun add @capgo/capacitor-updater

# Create account at capgo.app
bun add -g @capgo/cli
capgo login

# Initialize and deploy
capgo init
bun run build
capgo upload

Users get updates instantly. See the capgo-live-updates skill for details.

Resources

• Official Migration Guide: https://capacitorjs.com/docs/cordova/migrating-from-cordova-to-capacitor
• Capacitor Docs: https://capacitorjs.com/docs
• Plugin Search: https://github.com/Cap-go/awesome-capacitor
• Capgo Plugins: https://github.com/Cap-go?q=capacitor
• Community Forum: https://forum.ionicframework.com/c/capacitor

Migration Timeline Estimate

Post-Migration Benefits

After migrating from Cordova to Capacitor:

✅ Faster development - Direct access to Xcode/Android Studio ✅ Live updates - Deploy updates without app store review (with Capgo) ✅ Better TypeScript - Full type safety ✅ Modern APIs - Promise-based, async/await ✅ Active maintenance - Regular updates and improvements ✅ Better debugging - Native IDE debugging tools ✅ Improved performance - Optimized native bridge

Next Steps

1. Complete the migration using steps above
2. Test thoroughly on physical devices
3. Set up CI/CD (see capacitor-ci-cd skill)
4. Add live updates (see capgo-live-updates skill)
5. Submit to app stores (see capacitor-app-store skill)