Migrating a Web App Using Cordova to Capacitor

There are several steps required to fully migrate a web app using Cordova over to Capacitor.

Note that it's recommended to work in a separate code branch when applying these changes.

Add Capacitor

Begin by opening your project in a Terminal, then add Capacitor to a web app or an Ionic app.

Next, open config.xml and find the id field in the widget element. In this example, it's io.ionic.myapp.

<widget id="io.ionic.myapp" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">

Also find the Name of your app:

<name>MyApp</name>

Now, initialize Capacitor with this app information:

npx cap init [appName] [appId]

In this example, it would be npx cap init MyApp io.ionic.myapp. These values can be found in the newly created capacitor.config.json file.

Build your Web App

You must build your web project at least once before adding any native platforms.

This ensures that the www folder that Capacitor has been automatically configured to use as the webDir in capacitor.config.json actually exists.

Add Platforms

Capacitor native platforms exist in their own top-level folders. Cordova's are located under platforms/ios or platforms/android.

npx cap add ios
npx cap add android

Both android and ios folders at the root of the project are created. These are entirely separate native project artifacts that should be considered part of your app (i.e., check them into source control, edit them in their own IDEs, etc.). Additionally, any Cordova plugins that were previously added to the project via npm install (located under dependencies in package.json) are automatically installed by Capacitor into each new native project (minus any incompatible ones):

"dependencies": {
    "@ionic-native/camera": "^5.3.0",
    "@ionic-native/core": "^5.3.0",
    "@ionic-native/file": "^5.3.0",
    "cordova-android": "8.0.0",
    "cordova-ios": "5.0.0",
    "cordova-plugin-camera": "4.0.3",
    "cordova-plugin-file": "6.0.1",
}

Splash Screens and Icons

If you've previously created icon and splash screen images, they can be found in the top-level resources folder of your project. Follow this guide to move them over to each native project.

Migrate Plugins

Begin by auditing your existing Cordova plugins - it's possible that you may be able to remove ones that are no longer needed.

Next, review all of Capacitor's core plugins as well as community plugins. You may be able to switch to the Capacitor-equivalent Cordova plugin. Also note that some Capacitor plugins extend beyond mobile, including PWA and Desktop functionality, which Cordova traditionally hasn't had support for. For example, compare the Capacitor Camera to the Cordova Camera.

Some plugins may not match functionality entirely, but based on the features you need that may not matter.

Note that any plugins that are incompatible or cause build issues are automatically skipped.

Set Permissions

By default, the entire initial permissions requested for the latest version of Capacitor are set for you in the default native projects for both iOS and Android. However, you may need to apply additional permissions manually by mapping between plugin.xml and required settings on iOS and Android. Consult the iOS and Android configuration guides for info on how to configure each platform.

Additional Config.xml Fields

You may be curious about how other elements from config.xml work in Capacitor apps.

The Author element can be configured in package.json, but is not used by Capacitor or within your app:

<author email="email@test.com" href="http://ionicframework.com/">Ionic Framework Team</author>

Most of the allow-intent values are either not used or there are configurable alternatives in capacitor.config.json.

<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
<allow-intent href="tel:*" />
<allow-intent href="sms:*" />
<allow-intent href="mailto:*" />
<allow-intent href="geo:*" />

iOS edit-config elements need to be configured in Info.plist.

<edit-config file="*-Info.plist" mode="merge" target="NSCameraUsageDescription">
    <string>Used to take photos</string>
</edit-config>

It's impossible to cover every config.xml element available. However, most questions relating to "How do I configure X in Capacitor?" should be thought of as "How do I configure X in [platform] (iOS/Android)?" when searching online for answers.

Removing Cordova

Once you've tested that all migration changes have been applied and the app is working well, Cordova can be removed from the project. Delete config.xml as well as the platforms and plugins folders. Note that you don't technically have to remove Cordova, since Capacitor works alongside it. In fact, if you plan to continue using Cordova plugins or think you may in the future, you can leave the Cordova assets where they are.

Next Steps

This is just the beginning of your Capacitor journey. Learn more about using Cordova plugins in a Capacitor project or more details on the Capacitor development workflow.

Contributors

Back Next