← All posts

Migrating a React Native app to the New Architecture is a dependency audit with a flag at the end

Migrating a React Native app to the New Architecture is easy on paper. You enable a flag, rebuild, and enjoy a faster app. In practice the code you wrote is not the hard part. The code you depend on is.

We recently migrated a production app with about 35 third-party packages. Four of them blocked us. This is how we found them early, what we did about each, and what the app gained.

What actually changes

In the old architecture, JavaScript and native code talk through the bridge: calls are serialised, queued and handled asynchronously on the other side. The New Architecture removes that hop. JavaScript holds direct references to native objects through JSI, native modules become TurboModules that load only when first used, and the Fabric renderer takes over the UI.

Old bridge and New Architecture
Old architectureNew ArchitectureJavaScriptBridgeserialised,asynchronousNative modules andviewsJavaScriptJSIdirect callsTurboModules andFabrictyped by Codegen
The bridge serialises every call. JSI lets JavaScript call native code directly, with types generated by Codegen.

Your own screens mostly keep working. An interop layer lets many old-style modules and components run unchanged. The trouble starts with packages that reach into the bridge in ways the interop layer cannot hide.

The real work: 35 packages

Before touching the flag we audited every native dependency and sorted each into one of three buckets.

BucketWhat it meansWhat we did
ReadySupports the New Architecture, or runs cleanly through the interop layerNothing, apart from testing it
Needs updateA newer version adds supportUpgraded before the migration, as separate releases
Needs replacingNo support, unmaintained, or tied to the old bridgeReplaced it with a maintained alternative

Four of the roughly 35 packages blocked the migration outright. They either had no New Architecture support or relied on the old bridge in ways the interop layer could not cover.

Third-party packages in the app
~35packagesWorked, some after anupdate31 · 89%Blocked the migration4 · 11%

Doing the audit first changes the shape of the project. The upgrades and replacements happen on the old architecture, one at a time, each shipped and verified on its own. By the time the flag is enabled, most of the risk has already been released.

The approach that worked

  1. Step 1AuditEvery native dependency sorted into ready, needs update or needs replacing.
  2. Step 2RewriteTwo custom native modules became TurboModules with typed Codegen specs.
  3. Step 3ReplaceUnmaintained packages swapped for maintained ones instead of forked.
  4. Step 4Flag and testEnabled on a release branch, full regression on both platforms, then merged.

Rewriting our own modules

The app had two custom native modules. We rewrote both as TurboModules. The spec is a typed TypeScript file, and Codegen generates the native interfaces from it, so a mismatch between JavaScript and native code becomes a build error instead of a crash in production.

import type { TurboModule } from "react-native"
import { TurboModuleRegistry } from "react-native"

export interface Spec extends TurboModule {
  getDeviceToken(): Promise<string>
  setBadgeCount(count: number): void
}

export default TurboModuleRegistry.getEnforcing<Spec>("Notifications")

The module above is an illustration, not our client's code, but the shape is the same: the interface is the contract, and both platforms are generated from it.

Replace, do not fork

For the unmaintained packages we chose replacement over forking. A fork makes the migration pass today and leaves you owning native code you did not write, on two platforms, through every future React Native upgrade. A maintained alternative costs more this week and much less every month after.

The flag comes last

Only then did we enable the New Architecture, on a release branch, and run the full regression suite on both platforms before merging. A release branch keeps the main line shippable while the migration is verified, and makes the change easy to hold back if a late problem appears.

What the app gained

Cold start got about 15% faster, and the heavy list screens stopped dropping frames. Both follow from the architecture: modules load when they are first needed instead of all at startup, and the UI no longer waits for messages to cross the bridge.

~35
third-party packages audited
4
blocked the migration
~15%
faster cold start

What to take from it

  • Start with the dependency audit. It tells you the real size of the project before you commit to a date.
  • Ship upgrades and replacements separately, on the old architecture, so each change can be verified alone.
  • Prefer a maintained replacement to a fork. You are choosing who maintains that code for the next few years.
  • Give the flag its own release branch and a full regression pass.
The migration is not a flag flip. It is a dependency audit with a flag at the end.