Skip to content

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)
  1. What changed in 0.82: React Native runs only on the New Architecture
  2. Fabric, TurboModules and JSI in one table
  3. The path: 0.81 or SDK 54, enable the New Architecture, test libraries, upgrade
  4. How to tell if a library supports the New Architecture
  5. What to do when a library is not compatible
  6. Common mistakes
  7. Frequently asked questions
  8. 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:

VersionDateLegacy Architecture
0.76Oct 23, 2024New Architecture becomes the default; legacy still available
0.80Jun 12, 2025Frozen: no new features, warnings added
0.81 · SDK 54Aug 12, 2025 · Sep 10, 2025Last versions where you can still enable it
0.82Oct 8, 2025Can no longer be enabled; the flags are ignored
0.83 · SDK 55Dec 10, 2025 · Feb 25, 2026newArchEnabled removed from app.json
0.84Feb 11, 2026Its code leaves iOS builds; classes removed on Android
0.88 · SDK 58Oct 19, 2026 · Oct 15, 2026Current 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:

PieceWhat it replacesWhat changes for you
JSIThe asynchronous bridgeJavaScript holds a reference to a C++ object and calls its methods with no serialization
TurboModulesBridge-based Native ModulesLoaded only when used, can answer synchronously, typed through Codegen
FabricThe old rendererA C++ renderer shared across platforms; synchronous layout in useLayoutEffect, Suspense and transitions
CodegenHand-written contractsGenerates native code from a typed spec file
Interop layerNothing: it is a transition aidLets 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.

the old bridge vs. JSI in React Nativelegacy architectureJavaScriptbridgenativeserializedqueuedasyncevery call waits in lineNew ArchitectureJavaScriptJSI (C++)Fabric · TurboModulesdirectsynchronouslazy loadingthe call answers right awaysince 0.82 only the right side existssource: reactnative.dev, New Architecture is here (2024)

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:

  1. 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.
  2. 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 false someone left behind.
  3. Test your libraries in a development build: screens, camera, maps, payments, notifications, anything that touches native code.
  4. 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
  }
}
  1. The first grep looks for the option in the three places Expo documents. If you use app.config.ts, search there too.
  2. The second looks for the CocoaPods variable, which is sometimes hard-coded in the Podfile or in a package.json script.
  3. In app.json, "newArchEnabled": true enables it on SDK 54; since it is the default, you can also delete the line.
  4. 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.

the migration in four steps0.82: no way back from hereone version, one changetest before moving onstep 10.81 or SDK 54same architecturestep 2turn on New Archdevelopment buildstep 3test librariesscript + screensstep 4upgrade to 0.82+now 0.88 · SDK 58architecture first, version secondorder recommended by React Native 0.82 and Expo

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:

  • codegenConfig in its package.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);
  1. It reads the app's package.json (or the path you pass) and merges dependencies and devDependencies.
  2. 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.
  3. A library counts as native if it has an ios or android folder or a .podspec. Everything else is skipped.
  4. With codegenConfig, it ships New Architecture specs. With expo-module.config.json, it is an Expo module. With neither, it goes on the review list.
  5. 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.

native libraries: what to check in eachsignalwhat it meanswhat to docodegenConfigships New Arch specstest in a buildexpo-module.configan Expo moduletest in a buildJavaScript onlynot affectednothingnative, no specsinterop or breakscheck by handarchived repono fixes comingreplace itReact Native Directory: newArchitecture fieldnpx expo-doctor checks your dependencies against ita signal filters, the build is the proofsource: React Native and Expo docs, November 2026

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
  1. npm install expo@^55.0.0 moves the expo package to the next SDK. Repeat with 56, 57 and 58.
  2. npx expo install --fix aligns the other dependencies with the versions that SDK expects.
  3. npx expo-doctor checks 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=false still 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/ or android/.
  • 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 newArchEnabled to false or RCT_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-doctor passes, 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

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 19, 2026

← Blog