Cordova to Capacitor Migration Guide | Step-by-Step Migration Process

Why Migrate from Cordova to Capacitor

Apache Cordova has served as the standard for hybrid app development for many years, but as of 2026, many development teams are proceeding with migration to Capacitor. Capacitor is a next-generation framework whose design involved Cordova development team members, with many improvements addressing Cordova's constraints. At Oflight Inc. in Shinagawa-ku, we have successfully completed over 15 Cordova to Capacitor migration projects in the past two years. Main reasons for migration include improved development efficiency through direct native project management, rapid access to the latest iOS/Android APIs, type safety through full TypeScript support, and integration with modern toolchains. Companies in Minato-ku and Shibuya-ku are implementing planned migrations to eliminate technical debt and improve maintainability. The declining support trend for Cordova is also an important factor in considering migration.

Pre-Migration Preparation - Project Assessment and Risk Analysis

Detailed assessment of your current Cordova project is essential before starting Capacitor migration. First, review config.xml and create a list of Cordova plugins in use. Development teams in Setagaya-ku conducted plugin inventory and verified Capacitor compatibility status in advance, enabling accurate migration timeline estimation. Next, evaluate the presence and scale of custom native code (iOS/Android). Projects in Meguro-ku had over 10 custom Cordova plugins, so they secured separate effort for rewriting these as Capacitor plugins. Inventorying existing build scripts and CI/CD pipelines is also important. Companies in Ota-ku developed detailed migration plans for updating build jobs on Jenkins to Capacitor compatibility. At Oflight in Shinagawa-ku, we provide free migration assessment services, supporting risk analysis and effort estimation.

Gradual Migration Strategy - Coexistence Period with Capacitor

Since Capacitor can coexist with Cordova, a gradual migration approach is recommended. First, install Capacitor in addition to your existing Cordova project, building a state where both runtimes operate. Startups in Shibuya-ku set this coexistence period at 2 months, gradually migrating to Capacitor plugins feature by feature. The key is not to replace all plugins at once but to migrate sequentially with prioritization. Financial app projects in Minato-ku first migrated authentication and push notification features to Capacitor, then proceeded to other features after sufficient testing periods. This gradual approach minimizes risk while allowing careful operational verification of each feature. Development teams in Setagaya-ku managed two branches in parallel, "cordova-main" and "capacitor-migration", as a branching strategy, achieving safe migration. At Oflight in Shinagawa-ku, we propose optimal migration strategies tailored to project scale and requirements.

Installing and Configuring Capacitor

Installing Capacitor into an existing Cordova project is easily executed with npm commands. After running `npm install @capacitor/core @capacitor/cli`, initialize the Capacitor project with `npx cap init`. At this time, specify the app name, app ID (Bundle Identifier), and web directory path. Development teams in Meguro-ku smoothly completed initial setup by inheriting the app ID from the existing config.xml. Next, add native platforms with `npx cap add ios` and `npx cap add android`. Projects in Ota-ku saw developers express surprise that Xcode and Android Studio projects were generated at this point, enabling direct access to native code. A capacitor.config.ts file is generated, where you describe web directory, server URL, plugin settings, etc. At Oflight in Shinagawa-ku, we provide optimal project configurations including TypeScript setup as templates.

Plugin Compatibility Check and Migration Planning

While many Cordova plugins work on Capacitor, not all are fully compatible. First, verify whether plugins in use can be replaced with official Capacitor plugins. Major functionality like Camera, Geolocation, File, Network, Device, and Storage is covered by official plugins. Development teams in Shibuya-ku found that 15 out of 20 Cordova plugins could be replaced with official Capacitor plugins. Next, check Capacitor Community plugins. Popular plugins like Stripe, Facebook Login, and Google Analytics have community versions. EC apps in Minato-ku significantly reduced custom development effort by leveraging community plugins. For plugins without compatibility, re-implementation as custom Capacitor plugins is necessary. Projects in Setagaya-ku rewrote proprietary barcode scanner plugins in Swift/Kotlin, achieving improved performance. At Oflight in Shinagawa-ku, we professionally support plugin compatibility investigation and migration plan development.

Removing Cordova Plugins and Adding Capacitor Plugins

In actual plugin migration work, first uninstall Cordova plugins and install corresponding Capacitor plugins. For example, remove `cordova-plugin-camera` and add `@capacitor/camera`. Development teams in Meguro-ku created migration scripts to automate plugin replacement. The important point is that plugin call APIs in JavaScript code also need updating. Change from Cordova's global object-based API (such as `navigator.camera`) to Capacitor's import-based module syntax (`import { Camera } from '@capacitor/camera'`). In Vue projects in Ota-ku, this change enabled IDE autocomplete and TypeScript type checking, dramatically improving the development experience. Some plugins have different API signatures, so migrate carefully while referring to official documentation. At Oflight in Shinagawa-ku, we have documented migration patterns for major plugins to streamline migration work.

Migrating Build Configuration - from config.xml to capacitor.config

Configuration items described in Cordova's config.xml need to be migrated to Capacitor's capacitor.config.ts. Basic settings like app name, bundle ID, and version information are managed in both capacitor.config.ts and native projects (Info.plist, build.gradle). Development teams in Shibuya-ku were initially confused by this dual management, but appreciated being able to directly edit native projects for more granular control. Content Security Policy (CSP) settings are managed in meta tags within index.html. Security-focused apps in Minato-ku strictly defined CSP settings, strengthening protection against XSS attacks. Permission settings (camera, location, etc.) are described directly in Info.plist for iOS and AndroidManifest.xml for Android. Projects in Setagaya-ku saw significantly increased freedom in permission descriptions by being able to edit directly in Xcode and Android Studio. At Oflight in Shinagawa-ku, we provide configuration migration checklists from config.xml to support complete migration.

Converting Custom Cordova Plugins to Capacitor Plugins

In-house developed Cordova plugins need to be rewritten in Capacitor plugin format. Capacitor plugins consist of a TypeScript/JavaScript frontend layer and Swift (iOS)/Kotlin (Android) native layers. Development teams in Meguro-ku modernly rewrote Cordova plugins written in Objective-C and Java in Swift and Kotlin, improving code readability and maintainability. Using the `@capacitor/cli` command `npx cap plugin:generate` auto-generates plugin boilerplate code. Projects in Ota-ku leveraged this command to significantly shorten initial plugin development setup. Capacitor plugins standardize on Promise-based asynchronous APIs, avoiding callback hell. Development teams in Minato-ku dramatically improved code readability by leveraging async/await syntax. Plugin testing uses both real devices and simulators. At Oflight in Shinagawa-ku, we support all phases of custom plugin development, ensuring high-quality plugin implementation.

Optimizing Build and Debug Workflow

Since Capacitor uses Xcode and Android Studio directly, the debugging experience is dramatically improved compared to Cordova. After building the web app, reflect to the native project with `npx cap sync`, then launch the app from Xcode or Android Studio. Development teams in Shibuya-ku expressed amazement at being able to debug Swift code using Xcode's breakpoint functionality. Enabling the live reload feature immediately reflects web code changes in the app. Projects in Setagaya-ku combined Vite's fast HMR (Hot Module Replacement) with Capacitor's live reload, increasing development speed by 3x compared to before. Android Studio's logcat and layout inspector are also usable just like native development. Development teams in Minato-ku seamlessly track web and native bugs by using Chrome DevTools and native debuggers together. At Oflight in Shinagawa-ku, we support optimal debug environment construction and workflow improvement.

Updating CI/CD Pipelines

Cordova-based CI/CD pipelines need to be updated for Capacitor compatibility. The basic flow is web app build, running `npx cap sync`, and native app build. Development teams in Meguro-ku updated GitHub Actions workflow files to achieve automated builds and tests. For iOS, Xcode builds and TestFlight distribution can be automated using Fastlane. Companies in Ota-ku centrally managed certificates and provisioning profiles with Fastlane Match, improving team development efficiency. For Android, build with Gradle commands and enable automatic upload to Google Play Console. Projects in Shibuya-ku shortened QA cycles from weekly to daily through automatic delivery to internal testing tracks. Introducing Capacitor Live Updates enables automatic JavaScript bundle hotfix delivery from CI/CD pipelines. At Oflight in Shinagawa-ku, we comprehensively support CI/CD pipeline construction according to enterprise requirements.

Common Migration Issues and Solutions

Here are common issues encountered during Capacitor migration and their solutions. "Plugin not working" issues are often caused by missing permission settings. Projects in Minato-ku resolved this by adding camera usage description text to Info.plist. "WebView showing blank screen" issues are often caused by server URL configuration mistakes or CORS errors. Development teams in Setagaya-ku correctly configured the server option in capacitor.config.ts to establish connection to the development server. "Build errors occurring" issues can be due to Swift version mismatches or Gradle version problems. Projects in Meguro-ku updated Xcode to the latest version and resolved Swift compilation errors. "Existing Cordova plugins cannot load" issues can be caused by differences in plugin initialization timing. Teams in Ota-ku implemented a compatibility layer using the Capacitor.Plugins namespace to circumvent the problem. At Oflight in Shinagawa-ku, we provide specialized troubleshooting knowledge and support to smoothly advance migration.

Oflight's Migration Support Services

Oflight Inc., based in Shinagawa-ku, Tokyo, professionally supports migration from Cordova to Capacitor. We have a track record of successfully guiding Cordova app migration projects for many companies throughout Tokyo, including Minato-ku, Shibuya-ku, Setagaya-ku, Meguro-ku, and Ota-ku. We provide end-to-end support from pre-migration project assessment, detailed migration planning, plugin compatibility investigation, implementation support, testing and quality assurance, to release support. Custom Cordova plugin conversion to Capacitor plugins is handled by engineers with Swift/Kotlin native development skills. Migration of existing build scripts and CI/CD pipelines is compatible with various CI environments including GitHub Actions, Jenkins, and CircleCI. Our experienced team provides comprehensive support to minimize migration risks and smoothly migrate to Capacitor with zero downtime. If you are considering migration from Cordova to Capacitor, please contact Oflight. We will help evolve your mobile app to next-generation technology.