Migrating to the New Architecture: A Field Guide from 8 Migrations

Since React Native 0.82, the New Architecture is no longer optional. Apps that stayed on the legacy architecture are now stuck: they can't take new React Native or Expo versions, and the libraries they depend on are moving to New-Architecture-only releases. For those apps, migrating is the price of staying current.

I've migrated eight production apps to the New Architecture. This is the process I'd follow for a React Native New Architecture migration today: auditing dependencies, the upgrade path through 0.81, the breakages that come up most, and how to test and release without surprising your users.

Key takeaways

• Upgrade to React Native 0.81 (Expo SDK 54) first, the last versions that still support the legacy architecture, so you can switch architectures without also jumping versions.
• Audit every native dependency for New Architecture support before flipping the switch. Replace abandoned libraries.
• The interop layer helps older libraries run on the New Architecture, but treat it as a bridge to replacement, not a destination.
• Expect breakages in custom native modules, native views, imperative APIs and layout edge cases.
• Release behind a staged rollout with crash reporting watching, then continue upgrading past 0.82.

Step 1: audit your dependencies

List every package with native code (anything with ios or android folders, or a config plugin). For each, check:

• Does the current version support the New Architecture? The React Native Directory marks New Architecture support for listed libraries.
• Is it still maintained? An unmaintained library with native code is the most common blocker.
• Is there a modern replacement? Often there is, and it's better anyway.

Step 2: get to React Native 0.81 (or Expo SDK 54)

If you're several versions behind, upgrade in steps on the legacy architecture first, using the React Native Upgrade Helper diff for bare projects or one Expo SDK at a time with npx expo install --fix. Keep the app shippable at each step. Changing versions and architecture at the same time makes every bug ambiguous.

Step 3: enable the New Architecture

• Expo: set newArchEnabled: true in your app config (on SDK 54 and earlier), then rebuild.
• Bare React Native: set newArchEnabled=true in android/gradle.properties, and for iOS run RCT_NEW_ARCH_ENABLED=1 bundle exec pod install, then rebuild.

Build both platforms in release mode, launch, and keep a list of every warning and crash.

Step 4: fix what breaks

The breakages that come up most:

Work through them one by one, committing each fix, and keep a short log of what changed and why, so reviewers and future upgrades can follow the reasoning. Resist the urge to "also refactor this while we're here".

Step 5: test like you mean it

• Every screen on both platforms, in release builds, including rarely used flows such as settings, edge-case errors and onboarding.
• Native features: camera, maps, Bluetooth, payments, push, deep links, background tasks.
• Performance: startup time, list scrolling and animations on a mid-range Android device, compared with the old build.
• Automated end-to-end tests on the critical paths (sign-in, purchase, core flow) if you have them; this is when they pay off.

Step 6: release gradually, then keep going

Ship the migrated version with a phased release on iOS and a staged rollout on Android, and compare crash-free sessions with the previous version before widening. Once it's stable, continue upgrading past 0.82, where the New Architecture is the only option, and take the newer library versions that require it.

From the field: Across eight migrations, together with Hermes, image optimisation and cache-first fetching, load time dropped by about 60% (3.8 seconds to 1.5) while animations held a stable 60fps. If I had to give one rule to anyone starting a migration: do the dependency audit first, and release each step before beginning the next.

How long does it take?

It depends almost entirely on your native dependencies. An Expo app using maintained libraries can switch in days. A bare app with custom native modules, old native views and abandoned libraries can take weeks, mostly in replacing and retesting those pieces. The audit in step 1 is the best predictor, so do it before estimating.

FAQ

How do I migrate my React Native app to the New Architecture?

Audit native dependencies for support, upgrade to React Native 0.81 or Expo SDK 54 on the legacy architecture, enable the New Architecture, fix custom modules, native views and incompatible libraries, test every flow on both platforms in release builds, then release gradually and continue upgrading.

Can I still disable the New Architecture?

Not on current versions. From React Native 0.82, attempts to switch back to the legacy architecture are ignored, and Expo SDK 54 was the last SDK to support it. Apps that need the legacy architecture are effectively frozen on older versions.

What is the interop layer?

It's a compatibility layer that lets many libraries written for the legacy architecture run on the New Architecture without changes. It's useful during migration, but libraries should be updated or replaced, because the long-term direction is removing legacy code.

How long does a New Architecture migration take?

From a few days for an up-to-date Expo app with maintained libraries, to several weeks for a bare app with custom native modules, old native views and abandoned dependencies. A dependency audit gives you a realistic estimate before you start.

Next steps

If your app is stuck on the old architecture or an old React Native version, I can audit it, give you a migration estimate, and carry it through to release. Get in touch, or see how I work as a React Native developer.

Sources

• About the New Architecture, React Native docs
• React Native 0.82, React Native blog
• React Native Directory, React Native Directory
• React Native Upgrade Helper, React Native Community
• Upgrading Expo SDK, Expo