1# Migrating from react-navigation to expo-router
2 
3In SDK 56+, application code must not import from `@react-navigation/*` directly. Repoint those imports to the matching `expo-router` entry points. Runtime API is unchanged — only the module specifiers move.
4 
5## Steps
6 
71. Prefer the automated codemod (see below). If it is not viable, fall back to the manual mapping.
82. Replace imports using the table. Use the entry point that matches the `@react-navigation/*` source.
93. After rewriting, check whether any of the rewritten imports are deprecated in `expo-router` (see [Check for deprecated imports](#check-for-deprecated-imports)). If so, surface the deprecation reason and the suggested replacement to the user before continuing.
104. Validate: search for remaining `@react-navigation/` references in source files, then run typecheck/build/start.
115. Remove `@react-navigation/*` packages that are no longer imported from `package.json` and reinstall (delete `node_modules` if needed).
12 
13## Automated migration (preferred)
14 
15Run from the project root over your application code (replace `src` with the actual directory or glob):
16 
17```sh
18npx expo-codemod sdk-56-expo-router-react-navigation-replace src
19```
20 
21```sh
22npx expo-codemod sdk-56-expo-router-react-navigation-replace '**/*.{ts,tsx,js,jsx}'
23```
24 
25## Manual API mapping
26 
27| React Navigation source               | Expo Router target                                                       |
28| ------------------------------------- | ------------------------------------------------------------------------ |
29| `@react-navigation/native`            | `expo-router/react-navigation`                                           |
30| `@react-navigation/core`              | `expo-router/react-navigation`                                           |
31| `@react-navigation/elements`          | `expo-router/react-navigation`                                           |
32| `@react-navigation/routers`           | `expo-router/react-navigation`                                           |
33| `@react-navigation/stack`             | `expo-router/js-stack`                                                   |
34| `@react-navigation/bottom-tabs`       | `expo-router/js-tabs`                                                    |
35| `@react-navigation/material-top-tabs` | `expo-router/js-top-tabs`                                                |
36| `@react-navigation/native-stack`      | No direct equivalent. Use the `Stack` layout from `expo-router` instead. |
37 
38**Stack caveat:** Do NOT rewrite `import { Stack } from "expo-router"` to `expo-router/js-stack`. The root `Stack` is the Expo Router layout component used in route files; only use `expo-router/js-stack` when replacing a `@react-navigation/stack` JS stack navigator.
39 
40If you encounter a symbol that has no replacement, ask the user to file an issue in the `expo/expo` repository describing what is needed and why.
41 
42## Check for deprecated imports
43 
44A successful rewrite to `expo-router/*` does not guarantee the new import is the recommended one. Some symbols are re-exported as deprecated shims and the project may need to migrate further (for example, to a different `expo-router` API or to a first-party Expo package).
45 
46For each symbol rewritten in step 2:
47 
481. Resolve the rewritten module to its source in `node_modules` (e.g., `node_modules/expo-router/build/react-navigation.d.ts`, `js-stack`, `js-tabs`, `js-top-tabs`).
492. Look for a `@deprecated` JSDoc tag on the named export, or a runtime deprecation warning in the implementation file.
503. If deprecated, capture both the reason and the recommended replacement from the JSDoc/comment.
514. Report each deprecated symbol to the user with: the import path, the symbol, the deprecation reason, and the suggested replacement. Wait for the user to confirm before mass-applying further changes.
52 
53## Done when
54 
551. No `@react-navigation/*` imports remain in source files.
562. No unused `@react-navigation/*` entries remain in `package.json`.
573. Typecheck and bundler start without `@react-navigation/*` errors.
58 
59## Reference
60 
61- Official Expo Router SDK 55 → 56 migration guide: https://docs.expo.dev/router/migrate/sdk-55-to-56
62