DEV Community

Cover image for Migrating from React Navigation to Expo Router: A Step-by-Step Guide (With a Cheat Sheet)
Russel Dsouza
Russel Dsouza

Posted on

Migrating from React Navigation to Expo Router: A Step-by-Step Guide (With a Cheat Sheet)

Expo Router is built on React Navigation, so most of what you know carries over. Migration is mostly moving screens into an app/ folder: each navigator becomes a _layout.tsx, each screen becomes a file, navigation.navigate('Name', params) becomes router.push('/path'), route.params becomes useLocalSearchParams(), and your linking config disappears because every route is a deep link automatically. The cheat sheet at the end maps every common API.

If your app was started a few years ago, it probably has an App.tsx with a NavigationContainer, a stack, a tab navigator and a linking config that nobody wants to touch. Expo Router replaces that config with your folder structure. Here's how to get there without breaking the app.

Before you start

  • Your app should run on a recent Expo SDK. Upgrade first if you're several versions behind; doing both at once makes failures hard to trace.
  • Draw your current navigation tree. List every navigator, every screen and how screens nest. This becomes your folder structure.
  • Work on a branch, and for anything larger than a handful of screens, plan to migrate one navigator at a time and test each.

Step 1: Install and configure Expo Router

npx expo install expo-router react-native-safe-area-context react-native-screens expo-linking expo-constants expo-status-bar
Enter fullscreen mode Exit fullscreen mode

Point your app's entry at Expo Router in package.json:

{
  "main": "expo-router/entry"
}
Enter fullscreen mode Exit fullscreen mode

Add a URL scheme and the plugin in app.json:

{
  "expo": {
    "scheme": "myapp",
    "plugins": ["expo-router"]
  }
}
Enter fullscreen mode Exit fullscreen mode

Expo Router renders its own navigation container, so your NavigationContainer in App.tsx goes away. Keep the old App.tsx open in another tab; you'll copy pieces from it.

Step 2: Turn your navigator tree into folders

Say your current setup looks like this:

// Before: App.tsx
const Stack = createNativeStackNavigator();
const Tab = createBottomTabNavigator();

function MainTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen name="Home" component={HomeScreen} />
      <Tab.Screen name="Settings" component={SettingsScreen} />
    </Tab.Navigator>
  );
}

export default function App() {
  return (
    <NavigationContainer linking={linking}>
      <Stack.Navigator>
        <Stack.Screen name="Main" component={MainTabs} options={noHeader} />
        <Stack.Screen name="Project" component={ProjectScreen} />
        <Stack.Screen name="NewProject" component={NewProjectScreen} options={modal} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}
Enter fullscreen mode Exit fullscreen mode

The same tree as files:

app/
├── _layout.tsx            # was: the root Stack.Navigator
├── (tabs)/
│   ├── _layout.tsx        # was: MainTabs (Tab.Navigator)
│   ├── index.tsx          # was: "Home"      → /
│   └── settings.tsx       # was: "Settings"  → /settings
├── projects/
│   └── [id].tsx           # was: "Project"   → /projects/42
└── new-project.tsx        # was: "NewProject" (modal) → /new-project
Enter fullscreen mode Exit fullscreen mode

The (tabs) group organizes files without appearing in URLs, which is why Home lives at /.

Step 3: Recreate navigators as layouts

The root stack:

// app/_layout.tsx
import { Stack } from 'expo-router';

const noHeader = { headerShown: false };
const projectOptions = { title: 'Project' };
const modal = { presentation: 'modal', title: 'New project' } as const;

export default function RootLayout() {
  return (
    <Stack>
      <Stack.Screen name="(tabs)" options={noHeader} />
      <Stack.Screen name="projects/[id]" options={projectOptions} />
      <Stack.Screen name="new-project" options={modal} />
    </Stack>
  );
}
Enter fullscreen mode Exit fullscreen mode

The tabs:

// app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';

const homeOptions = { title: 'Home' };
const settingsOptions = { title: 'Settings' };

export default function TabsLayout() {
  return (
    <Tabs>
      <Tabs.Screen name="index" options={homeOptions} />
      <Tabs.Screen name="settings" options={settingsOptions} />
    </Tabs>
  );
}
Enter fullscreen mode Exit fullscreen mode

Screen options are the same React Navigation options you already use. A drawer works the same way with Drawer from expo-router/drawer (after installing the React Navigation drawer package).

Step 4: Move your screens

Each screen file default-exports the component. You can keep your existing screen components where they are and re-export them, which keeps the diff small:

// app/projects/[id].tsx
export { default } from '@/screens/ProjectScreen';
Enter fullscreen mode Exit fullscreen mode

Then update each screen's navigation calls (next step). Moving the files physically into app/ can come later.

Step 5: Replace navigation calls

Navigating:

// Before
navigation.navigate('Project', { id: project.id });

// After
import { router } from 'expo-router';
router.push(`/projects/${project.id}`);
Enter fullscreen mode Exit fullscreen mode

For more complex params, use the object form, which encodes values for you:

const target = { pathname: '/projects/[id]', params: { id: project.id, tab: 'files' } } as const;
router.push(target);
Enter fullscreen mode Exit fullscreen mode

Reading params:

// Before
const { id } = route.params;

// After
import { useLocalSearchParams } from 'expo-router';
const { id } = useLocalSearchParams<{ id: string }>();
Enter fullscreen mode Exit fullscreen mode

Params are now always strings, because they live in the URL. If you used to pass numbers, booleans or whole objects, parse numbers and booleans explicitly, and pass an ID instead of an object, then load the data on the screen. That second change is what makes every screen work from a deep link.

Going back and replacing: navigation.goBack() becomes router.back(), and navigation.replace(...) becomes router.replace(...).

Setting options from a screen: render a Stack.Screen inside the screen, or keep using useNavigation() and setOptions, which still works because Expo Router is built on React Navigation:

import { Stack } from 'expo-router';

const options = { title: project.name };
return (
  <>
    <Stack.Screen options={options} />
    {/* screen content */}
  </>
);
Enter fullscreen mode Exit fullscreen mode

Focus effects: import useFocusEffect from expo-router instead of React Navigation.

Step 6: Migrate your auth flow

The classic React Navigation pattern renders different screens depending on whether the user is signed in. In Expo Router, put each side in a group and guard it in one layout:

app/
├── _layout.tsx
├── (auth)/sign-in.tsx
└── (app)/(tabs)/...
Enter fullscreen mode Exit fullscreen mode

Recent Expo Router versions support protected routes with Stack.Protected and a guard prop; on older versions, a <Redirect href="/sign-in" /> in the protected group's layout does the same job. Either way, deep links into protected screens respect the guard, which the old conditional-screens pattern didn't always handle cleanly.

Step 7: Delete your linking config

This is the satisfying part. Your linking object with its screens mapping can be deleted: every file in app/ is a route, and with your scheme set, myapp://projects/42 opens the project screen with id: "42".

Search your codebase for code that built URLs by hand for notifications or emails and replace it with the new paths. Push notification handlers that called navigation.navigate should now call router.push with a path.

Step 8: Test it

  • Run through every screen from the old navigation tree, including back gestures and Android's back button.
  • Open deep links for each important route, with the app open and closed.
  • Use typed routes (enable typedRoutes under experiments in your app config, if your SDK version doesn't already enable it) so TypeScript catches every outdated path string.
  • For automated tests, Expo Router provides testing utilities (expo-router/testing-library) that render a file-based route tree in Jest.

The cheat sheet

  • NavigationContainer → removed; Expo Router provides it
  • createNativeStackNavigator → Stack in a _layout.tsx
  • createBottomTabNavigator → Tabs in a _layout.tsx
  • Stack.Screen name="Profile" → app/profile.tsx
  • Screen with params → app/profile/[id].tsx
  • navigation.navigate('Profile', params) → router.push('/profile/42')
  • navigation.goBack() → router.back()
  • navigation.replace(...) → router.replace(...)
  • route.params → useLocalSearchParams()
  • navigation.setOptions → <Stack.Screen options> in the screen (or useNavigation().setOptions)
  • useFocusEffect from React Navigation → from expo-router
  • Conditional auth screens → route groups + Stack.Protected or Redirect
  • linking config → deleted; routes are deep links automatically

Common migration mistakes

  • Detail screens inside the tabs folder, so they render under the tab bar. Keep them on the root stack.
  • Passing objects as params. Pass IDs and load data on the screen.
  • Forgetting that params are strings, so id === 42 silently becomes false.
  • Two index.tsx files resolving to the same path in different groups. Groups don't add URL segments, so their routes can collide.
  • Migrating navigation and upgrading the SDK in one go. Do one, then the other.

Conclusion

Moving from React Navigation to Expo Router is mostly a restructuring job: navigators become layouts, screens become files, navigation calls become paths and your linking config disappears. Do it one navigator at a time, pass IDs instead of objects and let typed routes catch the rest.

If you're starting a new app instead of migrating one, RapidNative generates React Native apps that already use Expo Router, which you can export as a standard Expo project.

How big was your navigation config before migrating? Share your before-and-after in the comments.

Top comments (0)