Archive Expo Snack Discord and Forums Newsletter

Install Expo Router

Learn how to quickly get started by creating a new project with Expo Router or adding the library to an existing project.

Find the steps below to create a new project with Expo Router library or add it to your existing project.

Quick start

We recommend creating a new Expo app using create-expo-app. This will create a minimal project with the Expo Router library already installed. To create a project, run the command:

Terminal

- npx create-expo-app@latest --template tabs@50

Now, you can start your project by running:

Terminal

- npx expo start

To view your app on a mobile device, we recommend starting with Expo Go. As your application grows in complexity and you need more control, you can create a development build.
Open the project in a web browser by pressing w in the Terminal UI. Press a for Android (Android Studio is required), or i for iOS (macOS with Xcode is required).

Manual installation

Ensure the version of Expo Router is compatible with the Expo SDK version your project is using.

Expo SDK	Expo Router
50.0.0	3.0.0
49.0.0	2.0.0
48.0.0	1.0.0

Prerequisites

Make sure your computer is set up for running an Expo app.

Create an Expo project

To create a new project, run the following command:

Terminal

- npx create-expo-app

Install dependencies

You'll need to install the following dependencies:

Terminal

-

npx expo install expo-router react-native-safe-area-context react-native-screens expo-linking expo-constants expo-status-bar

The above command will install versions of these libraries that are compatible with the Expo SDK version your project is using.

Terminal

-

npx expo install expo-router react-native-safe-area-context react-native-screens expo-linking expo-constants expo-status-bar react-native-gesture-handler

The above command will install versions of these libraries that are compatible with the Expo SDK version your project is using.

Setup entry point

For the property main, use the expo-router/entry as its value in the package.json. The initial client file is app/_layout.js.

package.json

{
  "main": "expo-router/entry"
}

Either delete the entry point in your package.json or replace it with index.js to be explicit:

package.json

{
  "main": "index.js"
}

Create a new file index.js in the root of your project. If it exists already, replace it with the following:

index.js

import 'expo-router/entry';

Modify project configuration

Add a deep linking scheme in your app config:

app.json

{
  "scheme": "your-app-scheme"
}

If you are developing your app for web, install the following dependencies:

Terminal

- npx expo install react-native-web react-dom

Then, enable Metro web support by adding the following to your app config:

app.json

{
  "web": {
    "bundler": "metro"
  }
}

Modify babel.config.js

Ensure you use babel-preset-expo as the preset, in the babel.config.js file or delete the file:

babel.config.js

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
  };
};

If you're upgrading from a version of Expo Router that is older than v3, remove the plugins: ['expo-router/babel']. expo-router/babel was merged in babel-preset-expo in SDK 50 (Expo Router v3).

Add expo-router/babel plugin as the last item in the plugins array to your project's babel.config.js:

babel.config.js

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: ['expo-router/babel'],
  };
};

Clear bundler cache

After updating the Babel config file, run the following command to clear the bundler cache:

Terminal

- npx expo start -c

If you're upgrading from an older version of Expo Router, ensure you remove all outdated Yarn resolutions or npm overrides in your package.json. Specifically, remove metro, metro-resolver, react-refresh resolutions from your package.json.

Expo Router requires at least react-refresh@0.14.0. React Native hasn't upgraded as of SDK 49 / Expo Router v2, so you need to force upgrade your react-refresh version by setting a Yarn resolution or npm override.

package.json

{
  %%placeholder-start%%... %%placeholder-end%%
  "resolutions": {
    "react-refresh": "~0.14.0"
  }
}

package.json

{
  %%placeholder-start%%... %%placeholder-end%%
  "overrides": {
    "react-refresh": "~0.14.0"
  }
}

Expo Router requires at least metro@0.76.0. If you are using Expo SDK version below 49, you will need to force upgrade your metro version by setting a Yarn resolution or npm override.

package.json

{
  "resolutions": {
    "metro": "0.76.0",
    "metro-resolver": "0.76.0"
  }
}

package.json

{
  "overrides": {
    "metro": "0.76.0",
    "metro-resolver": "0.76.0"
  }
}