React Native New Architecture: how to migrate from 0.81 and SDK 54
From the work/ 12 min read
Since 0.82 the Legacy Architecture cannot be turned back on. The safe path from 0.81 or Expo SDK 54, and how to audit your native libraries first.
- React
- Migration
In this article (8)
- What changed in 0.82: React Native runs only on the New Architecture
- Fabric, TurboModules and JSI in one table
- The path: 0.81 or SDK 54, enable the New Architecture, test libraries, upgrade
- How to tell if a library supports the New Architecture
- What to do when a library is not compatible
- Common mistakes
- Frequently asked questions
- Checklist
Since React Native 0.82 you cannot turn the old architecture back on: the New Architecture (Fabric, TurboModules and JSI) is the only one. The last version that allows both is 0.81, or Expo SDK 54. The safe path: upgrade to that version, enable the New Architecture, test your libraries, then keep upgrading.
As of November 19, 2026, the latest release is React Native 0.88 (October 19, 2026), and Expo SDK 58 already ships it. If your app still runs on the Legacy Architecture, every release puts you further behind. Below: what changed, the migration order, and a script that tells you which native libraries need a manual check.
What changed in 0.82: React Native runs only on the New Architecture
The React Native 0.82 announcement (October 8, 2025) is direct: the New Architecture is the only architecture for that version and every later one. If you set newArchEnabled=false on Android, or install pods with RCT_NEW_ARCH_ENABLED=0 on iOS, those settings are ignored and the app runs on the New Architecture anyway. No error tells you. The switch is simply gone.
The same post names 0.81 and Expo SDK 54 as the last versions that allow the Legacy Architecture, and recommends migrating there first. Expo says the same in the SDK 54 changelog (September 10, 2025): it is the last SDK with Legacy Architecture support. In SDK 55 (February 25, 2026, React Native 0.83), the newArchEnabled option was removed from app.json.
Then the cleanup started. According to the React Native 0.84 post, Legacy Architecture code is no longer included in iOS builds by default, and several Android classes were removed, including LazyReactPackage and BridgeDevSupportManager. The interop layer, which lets libraries written for the old architecture run, is still in place. The timeline:
| Version | Date | Legacy Architecture |
|---|---|---|
| 0.76 | Oct 23, 2024 | New Architecture becomes the default; legacy still available |
| 0.80 | Jun 12, 2025 | Frozen: no new features, warnings added |
| 0.81 · SDK 54 | Aug 12, 2025 · Sep 10, 2025 | Last versions where you can still enable it |
| 0.82 | Oct 8, 2025 | Can no longer be enabled; the flags are ignored |
| 0.83 · SDK 55 | Dec 10, 2025 · Feb 25, 2026 | newArchEnabled removed from app.json |
| 0.84 | Feb 11, 2026 | Its code leaves iOS builds; classes removed on Android |
| 0.88 · SDK 58 | Oct 19, 2026 · Oct 15, 2026 | Current release |
Fabric, TurboModules and JSI in one table
In the old architecture, JavaScript and native code talked through an asynchronous bridge: every call was serialized, queued and processed later. The React Native team explains in New Architecture is here that this step became a bottleneck with frequent updates or large objects. The New Architecture replaces the bridge with three pieces:
| Piece | What it replaces | What changes for you |
|---|---|---|
| JSI | The asynchronous bridge | JavaScript holds a reference to a C++ object and calls its methods with no serialization |
| TurboModules | Bridge-based Native Modules | Loaded only when used, can answer synchronously, typed through Codegen |
| Fabric | The old renderer | A C++ renderer shared across platforms; synchronous layout in useLayoutEffect, Suspense and transitions |
| Codegen | Hand-written contracts | Generates native code from a typed spec file |
| Interop layer | Nothing: it is a transition aid | Lets old libraries run, but does not support custom Shadow Nodes or concurrent features |
Your JavaScript barely changes: components and hooks are the same. What changes is the boundary with native code, so the risk sits in libraries that ship code under ios/ or android/, not in your screens. A concrete example of the shift: an old native module handed you a value through a callback; a new one can return it directly, because JSI allows the synchronous call.
Scroll the figure sideways to see all of it
The path: 0.81 or SDK 54, enable the New Architecture, test libraries, upgrade
The official recommendation has an order, and for good reason: if you jump from an old release straight to 0.82 or later, you mix two problems (the version change and the architecture change) and you will not know which one broke what. The four steps:
- Upgrade to 0.81 or SDK 54 on the architecture you already use, and get the app stable there. Expo recommends upgrading one SDK at a time.
- Enable the New Architecture on that same version. It is already on by default in 0.81 and SDK 54, so the job is usually removing a
falsesomeone left behind. - Test your libraries in a development build: screens, camera, maps, payments, notifications, anything that touches native code.
- Upgrade to 0.82, or, today, keep going to the current release, one SDK at a time.
For step 2, find where it was turned off. The Expo guide to the New Architecture lists three places: the app config, gradle.properties and Podfile.properties.json:
# From the project root: where is it turned off?
grep -rn "newArchEnabled" app.json android/gradle.properties ios/Podfile.properties.json
grep -rn "RCT_NEW_ARCH_ENABLED" ios/Podfile package.json
# app.json (SDK 54): remove the false or set it to true
{
"expo": {
"newArchEnabled": true
}
}
- The first
greplooks for the option in the three places Expo documents. If you useapp.config.ts, search there too. - The second looks for the CocoaPods variable, which is sometimes hard-coded in the
Podfileor in apackage.jsonscript. - In
app.json,"newArchEnabled": trueenables it on SDK 54; since it is the default, you can also delete the line. - After the change, create a fresh development build. Expo Go is not enough for this test if you have your own native libraries.
Before you upgrade, decide how you get back if something goes wrong: which build stays available and how you restore it. The reasoning is the same as on the web, covered in a rollback plan before you deploy.
Scroll the figure sideways to see all of it
How to tell if a library supports the New Architecture
JavaScript-only libraries are not a concern: the architecture does not touch them. Libraries with native code are. There are three signals you can read from your own node_modules, offline:
codegenConfigin itspackage.json. This is the Codegen configuration TurboModules and Fabric components use, per the Turbo Native Modules docs. If it is there, the library ships New Architecture specs.expo-module.config.json. It is an Expo module, and the Expo Modules docs say they all support the New Architecture.- Native code with neither. It may work through the interop layer, or it may break. That is your manual review list.
This script sorts the dependencies in your package.json into those groups. Run it after npm install:
// audit-native-deps.mjs: list the dependencies that ship native code and what they declare.
// Usage: node audit-native-deps.mjs [path/to/app] (run after npm install)
import { readFileSync, existsSync, readdirSync } from "node:fs";
import { join } from "node:path";
const root = process.argv[2] ?? ".";
const app = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
const names = Object.keys({ ...app.dependencies, ...app.devDependencies }).sort();
const rows = [];
for (const name of names) {
const dir = join(root, "node_modules", name);
if (!existsSync(join(dir, "package.json"))) {
rows.push([name, "?", "not installed"]);
continue;
}
const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
const files = readdirSync(dir);
const native = files.includes("ios") || files.includes("android") || files.some((f) => f.endsWith(".podspec"));
if (!native) continue; // JavaScript only: the architecture does not affect it
const verdict = pkg.codegenConfig
? "codegenConfig: ships New Architecture specs"
: files.includes("expo-module.config.json")
? "Expo module: supports the New Architecture"
: "CHECK: native code, no codegenConfig";
rows.push([name, pkg.version, verdict]);
}
for (const [name, version, verdict] of rows) console.log(`${name.padEnd(34)} ${String(version).padEnd(9)} ${verdict}`);
const check = rows.filter((r) => r[2].startsWith("CHECK") || r[1] === "?").length;
console.log(`\n${rows.length} native or missing, ${check} to check by hand`);
process.exit(check ? 1 : 0);
- It reads the app's
package.json(or the path you pass) and mergesdependenciesanddevDependencies. - For each name it looks for the folder in
node_modules; if it is missing, it flags it as not installed, because it cannot inspect it. - A library counts as native if it has an
iosorandroidfolder or a.podspec. Everything else is skipped. - With
codegenConfig, it ships New Architecture specs. Withexpo-module.config.json, it is an Expo module. With neither, it goes on the review list. - It prints one line per native library and exits with code 1 when there is something to review, so you can use it in CI.
We ran it with Node 22 against a test folder of invented packages (one with codegenConfig, one Expo module, one JavaScript-only, two native without specs and one not installed). This is the actual output:
$ node audit-native-deps.mjs fixture
@acme/maps 1.4.0 CHECK: native code, no codegenConfig
expo-example-module 3.0.1 Expo module: supports the New Architecture
missing-lib ? not installed
old-native-lib 0.9.3 CHECK: native code, no codegenConfig
react-native-fast-thing 2.1.0 codegenConfig: ships New Architecture specs
5 native or missing, 3 to check by hand
The script is a filter, not a verdict. A library can have codegenConfig and still break in one of your flows, and one without it can work fine through the interop layer. For the review list there are two more sources. One is React Native Directory, where each library carries a newArchitecture field. The other is npx expo-doctor, which, per Expo, checks your dependencies against that directory's data. If a dependency is not listed there and you have already checked it, exclude it in package.json:
{
"expo": {
"doctor": {
"reactNativeDirectoryCheck": {
"exclude": ["old-native-lib"],
"listUnknownPackages": false
}
}
}
}
exclude takes exact package names and regex patterns; listUnknownPackages: false silences the warning about packages the directory does not know. The final test is always a development build with the New Architecture on, walking through the screens that use each library on the list.
Scroll the figure sideways to see all of it
What to do when a library is not compatible
The Expo guide gives the order. First, update the library to its latest version: many have added support and your project simply pinned an old one. Second, if it still fails, create a branch, remove the failing libraries until the app starts, and measure how much your app depends on each one. Third, look for a compatible replacement; the guide itself suggests, for example, expo-location instead of react-native-geolocation-service. Fourth, if there is no replacement, open an issue or a pull request on the library's repository with a minimal reproduction.
If you own the library, or your company maintains it, the way out is to migrate it: write its spec in TypeScript with the Native prefix, add codegenConfig to its package.json and regenerate. Some libraries have shipped versions that only work on the New Architecture: the SDK 54 notes say that if you need to stay on the Legacy Architecture, you can keep using Reanimated v3. Staying is a pause, not a plan. SDK 54 is the ceiling for the Legacy Architecture, and everything released after it is out of reach, such as Expo UI, stable since SDK 56, or the Expo Router v56 changes.
Once the app runs on the New Architecture on SDK 54, move up one SDK at a time, as the Expo upgrade walkthrough recommends:
npm install expo@^55.0.0
npx expo install --fix
npx expo-doctor
npm install expo@^55.0.0moves theexpopackage to the next SDK. Repeat with 56, 57 and 58.npx expo install --fixaligns the other dependencies with the versions that SDK expects.npx expo-doctorchecks for common problems, including compatibility data from React Native Directory.
If your project does not use Expo, React Native provides the Upgrade Helper, which shows every file change between two versions.
Common mistakes
- Jumping from an old release straight to 0.82 or later. You mix the version change with the architecture change and cannot tell what broke what.
- Assuming
newArchEnabled=falsestill works. Since 0.82 it is ignored without an error; the app runs on the New Architecture regardless. - Testing in Expo Go. To check your native libraries you need a development build.
- Reviewing only JavaScript dependencies. The risk is in the ones that ship
ios/orandroid/. - Treating a tool's output as proof. The directory and the script filter; the proof is opening the screens that use each library.
- Staying on SDK 54 with no exit date. Every new release leaves the app further behind and the migration bigger.
Frequently asked questions
What is the last React Native version that supports the Legacy Architecture?
0.81, or Expo SDK 54. Since 0.82 the New Architecture is the only one, and the flags to disable it are ignored.
Does my JavaScript code have to change?
Rarely. Components and hooks are the same. What changes is the boundary with native code, so the work is in native libraries and in any modules you wrote yourself.
Will the interop layer go away?
The 0.82 post says it stays in the codebase "for the foreseeable future" and that they will share updates before removing it. It was still there in 0.84. Do not treat it as a permanent fix: it does not support custom Shadow Nodes or concurrent features.
How long does the migration take?
It depends on how many native libraries you have and whether they already support it. An app with a few up-to-date native dependencies may be done at step 2; one with in-house modules and no specs needs each module migrated.
Checklist
- The app is on React Native 0.81 or Expo SDK 54, and stable.
- No file sets
newArchEnabledtofalseorRCT_NEW_ARCH_ENABLED=0. - A fresh development build runs with the New Architecture on.
- The audit script ran and every library on its list was tested by hand.
npx expo-doctorpasses, or every exclusion has a reason.- Every incompatible library is updated, replaced or reported.
- There is a plan to go back to the previous build if something fails.
- The upgrade continues one SDK at a time up to the current release.
The PDF guide has this checklist step by step and the method for auditing native libraries, with the script.
Saw this on Instagram? Comment ARQUITECTURA on the Reel and I'll send you the guide.
Written by

Published November 19, 2026