React Native New Architecture: The Real Migration

Q: Why does migrating to the React Native New Architecture take weeks if it is just a flag?

Because the flag was never the actual work. Since React Native 0.76 in October 2024 the New Architecture is the default, and enabling it on a fresh app or flipping the Bridgeless setting is genuinely trivial. The migration effort in a real, mature app lives in two places the flag does not touch. The first is third-party libraries: any native dependency — navigation, gesture handling, camera, maps, payments — that still targets the old bridge architecture has to be upgraded, replaced, or pinned, and your leverage over an unmaintained library is an issue thread rather than a code change. The second is your own custom native modules, which were written against the old NativeModules API and must be re-authored as TurboModules with Codegen specifications. React Native ships an automatic interop layer that keeps most old-architecture libraries working during the transition, which is what makes a gradual migration possible, but that layer has documented limits. The number that predicts your timeline is therefore not one flag; it is the count of native dependencies in your package.json and how many still target the old bridge. This is the same shape as any large migration: the easy majority flips quickly and the tail is where the project actually lives.

Q: What are JSI, TurboModules, Fabric, and Codegen?

They are the four parts of the New Architecture, and they are not interchangeable despite often being used as synonyms. JSI, the JavaScript Interface, is the foundational change: it replaces the old asynchronous, JSON-serialized bridge with direct, synchronous calls between JavaScript and C++, removing the serialization bottleneck that defined React Native performance for a decade. TurboModules are native modules built on JSI and loaded lazily, so application startup no longer pays the cost of initializing every native module whether or not it is used — you pay for a module when you first call it. Fabric is the new rendering system: it is concurrent and interruptible, and it aligns with React 18 concurrent features, which means rendering work can be prioritized and paused rather than blocking. Codegen is the tooling that generates strongly typed contracts between JavaScript and native code from your specifications, so the boundary between the two languages is checked at build time rather than failing at runtime. Together these remove the bridge and replace it with a typed, synchronous, lazily-loaded, concurrent foundation. Understanding which is which matters during migration because they fail and get adopted differently: JSI and Fabric are platform-level, while TurboModules and Codegen are where your own native-module rewrite work concentrates.

Q: Will my existing React Native libraries break on the New Architecture?

Most will keep working through the automatic interop layer, but the ones that matter most to a complex UI are the ones most likely to have problems, so you cannot assume and must audit. The interop layer is designed to let old-architecture native modules run under the New Architecture without changes, which is exactly what enables a gradual rather than big-bang migration. Its limits, which React Native documents, are the crucial detail: it does not support custom Shadow Nodes or Fabric concurrent features. In practice that means a simple old-architecture native module — one that exposes some methods to JavaScript — will typically ride the shim fine, while a library that renders its own native UI views, such as a maps SDK, a rich media player, or a custom charting component, is precisely the case the interop layer cannot fully cover, and it may degrade or fail. The correct process is to enumerate every native dependency in package.json, check each library New Architecture support status, and map it against that boundary: simple modules ride the shim and can be upgraded later, while view-rendering libraries need genuine New-Architecture versions before you can rely on them. Discovering a core navigation or gesture library is unsupported should happen in your week-one audit, not in QA after you have flipped the flag.

Q: How do I migrate my own custom native modules?

Re-author them as TurboModules with Codegen specifications, and schedule the work by traffic rather than trying to convert everything at once. Your custom native modules are the part of the migration you fully control, which is both good news and a reason to plan it deliberately instead of firefighting it. The process for each module is to write a Codegen spec that describes the module typed interface, then port the native implementation to the TurboModule interface. In return you get two concrete benefits beyond compatibility: the interface is now strongly typed and checked at build time, and the module is loaded lazily so it no longer adds to startup cost until it is actually used. The recommended sequencing is to convert your highest-traffic and most performance-sensitive modules first, so the startup and latency improvements appear early and help justify the continued investment in the migration, then work down to the rarely-used modules. Avoid the big-bang rewrite of every module in one change, because it produces an untestable diff and turns a series of verifiable steps into a single high-risk event. Each module conversion needs a native engineer familiar with the platform code rather than a JavaScript developer, so account for that in staffing — this is the part of the migration where iOS and Android native skills, not React skills, are the constraint.

Q: In which version did the New Architecture become the default?

React Native 0.76, released in October 2024, is when the New Architecture became the default, with React 18 enabled at the same time. Before 0.76 the only way to use the New Architecture was to opt in explicitly by setting flags in your Gradle properties and Podfile; from 0.76 onward a new app gets Bridgeless mode and the New Architecture without any manual toggle. It is important to be precise about the status of the old bridge, because there is misinformation on this point. According to React Native own announcement, the bridge remains in place for backward compatibility to support gradual migration, and while the team has stated it will remove the bridge code completely in the future, the announcement does not commit to a specific version for that removal. Similarly, the interop layer that provides backward compatibility with old-architecture libraries is slated for eventual removal, at which point modules will need to support the New Architecture directly, but again without a pinned version. The practical reading for planning is that you are not under an immediate deadline — old-architecture libraries and the bridge still function today — but the direction is unambiguous and one-way, so treating the migration as inevitable and scheduling it deliberately is wiser than pinning old versions and hoping the removal never comes.

Q: How much faster is the New Architecture, really?

It depends entirely on where your app is bottlenecked, and selling the migration as a guaranteed performance number is a mistake that gets the whole effort judged a failure. The architectural improvements are real and worth stating precisely. JSI removes the asynchronous JSON serialization of the old bridge, replacing it with direct synchronous calls, which eliminates a genuine latency and overhead source. Fabric concurrent rendering improves responsiveness by letting the renderer prioritize and interrupt work, which helps an app hold a 60fps budget, roughly a 16 ms frame. TurboModules cut startup cost by loading native modules lazily. But whether those translate into a visible win for your users depends on your specific app. An application that was genuinely bottlenecked on heavy bridge traffic — frequent, chatty native calls, large data crossing the boundary — can see a substantial improvement. An application bottlenecked on network latency, backend response times, or expensive JavaScript business logic will see much less, because the bridge was not its constraint. The honest way to set expectations is to migrate for the architecture and the future — the bridge is on a removal path and the ecosystem is building on the New Architecture next — rather than for a headline percentage. If you do want a performance case, measure your app actual bottlenecks first, so any number you promise is one you can actually deliver.

Q: Do I need to adopt Hermes for the New Architecture?

You should, because the New Architecture performance story assumes the Hermes JavaScript engine, and Hermes is the default. Hermes is the JavaScript engine built specifically for React Native, and the JSI-based synchronous native access at the heart of the New Architecture is tuned and validated against it. Running the older JavaScriptCore engine underneath the New Architecture is technically possible in some configurations but amounts to swimming upstream: you are combining a foundation optimized for one engine with a different engine, and you lose the alignment that much of the performance work depends on. The pragmatic approach is to treat the Hermes adoption as part of the same migration effort rather than deferring it to a separate later project, because doing both together means you test one combined change against your device matrix rather than sequencing two separate risky changes. Hermes also brings its own benefits that compound with the New Architecture, including improved startup time and lower memory usage from ahead-of-time bytecode compilation. If your app is already on Hermes, which is increasingly likely given it is the default, this is a non-issue; if it is still on JavaScriptCore, fold the switch into the New Architecture migration plan rather than treating it as optional.

Q: What is the biggest mistake teams make migrating to the New Architecture?

Flipping the flag before auditing the native dependency graph, which converts what should be a planned migration into an unplanned QA emergency. Because enabling the New Architecture is a one-line change, the tempting approach is to switch it on and see what breaks — and what breaks is discovered by testers, late, under pressure, often with a release deadline already committed. The disciplined alternative is to do the audit first: enumerate every dependency in package.json that has a native component, determine each one New Architecture support status, and map them against the interop layer real limits, because a single unsupported core library such as navigation or gesture handling can gate the entire app. A cluster of related mistakes follows from skipping that audit: assuming the interop layer covers everything when it explicitly does not handle custom Shadow Nodes or concurrent features; attempting a big-bang rewrite of all custom native modules at once instead of porting them by traffic in testable steps; promising stakeholders a performance improvement that depends on bottlenecks you have not measured; and treating a blocked third-party library as your engineering problem rather than deciding early whether to upgrade it, replace it, or contribute a fix upstream. Every one of these is avoided by the same principle: the flag is the last step of the migration, not the first, and the dependency audit is what turns weeks of surprises into a scheduled, testable sequence.