Skip to Content
v1.33.8 · shipped One-screen report · Looks like your app Read the changelog →
Migration guidesCordova → React Native

Cordova → React Native

Weeks High risk

A two-hop migration: stabilise on Capacitor first, then port screen-by-screen to React Native. This is the safest path if your Cordova app is non-trivial, because it lets you ship features the whole time instead of feature-freezing for a full rewrite.

If your app is small (a handful of screens, no deep native plugin dependencies) you can skip the Capacitor stop and port directly to RN. See Path B below.

This guide composes two existing guides. Read them in order: Cordova → Capacitor first, then Capacitor → React Native. Mushi Mushi stays on the same project the whole way through.

Why migrate

You’re on Cordova and want to end up on React Native because:

  • Performance. WebView-based shells can struggle with long scrolling lists, chat views and animations. React Native renders native views.
  • Native API access. Newer iOS / Android APIs (App Intents, WidgetKit, Health, etc.) are often reachable through Expo modules or community libraries.
  • Hiring. React Native engineers are usually easier to find than Cordova ones.

You should NOT migrate if:

  • You ship daily and cannot afford a feature freeze on the mobile surface.
  • Your differentiator is web-first SEO (RN Web is OK, but Next.js is better).
  • Your app is mostly a thin wrapper around a great mobile web experience.

Two paths

Path A: Cordova → Capacitor → React Native (recommended)

Lower-risk because you stay shippable at every step.

  1. Week 1-2. Migrate Cordova → Capacitor following that guide. Ship to production. This alone is a meaningful win (better debugging, modern WebView, modern plugin ecosystem).
  2. Week 3-8. Migrate Capacitor → React Native following that guide. Dual-ship for a couple of weeks before sunsetting the Capacitor build.

This is what we recommend for any app with > ~10 screens or > 5 native plugins.

Path B: Direct Cordova → React Native

Faster end-to-end, riskier mid-migration. Use only when:

  • Your app has a small surface area (≤ 10 screens, ≤ 5 native plugins).
  • You’re comfortable feature-freezing the mobile surface for the full migration window.
  • Your React/JS code is already well-isolated from Cordova plugin calls (you can swap call sites to RN equivalents directly).

Mushi Mushi during the migration

Identical to § 7 of the Capacitor → React Native plan : same project, same apiKey, dual-ship Cordova/Capacitor and RN at the same time, sunset the legacy build only after the RN one has been stable for a week in beta.

You’ll touch the Mushi Mushi SDK exactly once per hop:

  • Hop 1 (Cordova → Capacitor): replace @mushi-mushi/web in the WebView (if you used it) with @mushi-mushi/capacitor and call Mushi.configure({ projectId, apiKey }).
  • Hop 2 (Capacitor → React Native): swap that for @mushi-mushi/react-native and mount <MushiProvider projectId apiKey> at the app root.

No Mushi Mushi project yet? Create a free account  (no card) and a project before hop 1, so both builds report to it from the start. The Capacitor quickstart shows where the project ID and API key come from.

Migration checklist (Path A)

Migration checklist
8 required steps
  1. Step 01
    Audit Cordova plugins (per the Cap→RN plugin map)
  2. Step 02
    Hop 1: complete Cordova → Capacitor
  3. Step 03
    Verify Mushi Mushi reports flow on the Capacitor build
  4. Step 04
    Hop 2: bootstrap the RN project (current RN, New Architecture)
  5. Step 05
    Port screens one at a time
  6. Step 06
    Mount @mushi-mushi/react-native + smoke-test
  7. Step 07
    Dual-ship Capacitor + RN for ≥ 2 weeks
  8. Step 08
    Sunset the Cordova/Capacitor build

Migration checklist (Path B, direct)

Migration checklist
7 required steps
  1. Step 01
    Plugin audit (lower tolerance: every Cordova plugin needs an RN answer)
  2. Step 02
    Bootstrap a current React Native release with the New Architecture
  3. Step 03
    Port your design system to RN primitives or a kit (NativeWind / Tamagui)
  4. Step 04
    Port screens and feature-freeze the Cordova build
  5. Step 05
    Mount @mushi-mushi/react-native (same projectId / apiKey)
  6. Step 06
    Closed beta on TestFlight / Play Internal
  7. Step 07
    Cutover and sunset Cordova

Verification

  • The Mushi Mushi Reports page shows reports from @mushi-mushi/react-native sent from a real device.
  • Cold start on a mid-range Android device is no slower than the Cordova baseline (measure both; results vary by app).
  • The crash rate in beta is no worse than the Cordova build’s.

Rollback

The strength of Path A is that rollback is trivial at any step: if the RN build hits a wall in week 5, you simply keep shipping the Capacitor build and pause RN work. The Cordova build is also still in your git history if hop 1 itself goes sideways (rare but possible).

References

Last updated on
Cordova → CapacitorReact Native CLI ↔ Expo