Skip to Content
v0.8.0 · shippedNative iOS / Android / Flutter / Capacitor SDKs, A2A discovery, SOC 2 readiness, residency, BYO storage, BYOK. 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 the Direct path section below.

This guide composes two existing guides. Read them in order: Cordova → Capacitor first, then Capacitor → React Native. Mushi stays mounted 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 hit a ceiling on chat scrolls, large lists, and animations. RN’s JS-to-native bridge clears it.
  • Native API access. Modern iOS / Android APIs (App Intents, WidgetKit, Health, etc.) ship to RN faster than to Cordova or Capacitor.
  • Hiring. RN engineers are easier to find in 2026 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 during the migration

Identical to the Capacitor → React Native § 7 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 SDK exactly once per hop:

  • Hop 1 (Cordova → Capacitor): swap the legacy Cordova plugin for @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.

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 reports flow on the Capacitor build
  4. Step 04
    Hop 2: bootstrap the RN project (RN 0.83+, 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 RN 0.83 with the New Architecture
  3. Step 03
    Port your design system to RN primitives or a kit (NativeWind / Tamagui)
  4. Step 04
    Port screens — 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

  • Mushi inbox shows reports tagged with the new SDK on a real device.
  • Cold-start time on a mid-tier Android device drops by ≥ 30 % vs the Cordova baseline (rough sanity check; varies by app).
  • Crash rate is ≤ 0.5 % for the first 7 days of beta.

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