HomeGuidesReferenceLearn
ArchiveExpo SnackDiscord and ForumsNewsletter

Install Expo Router

Edit this page

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

1

We recommend creating a new Expo app using create-expo-app to create a project with Expo Router library already installed and configured:

Terminal
- npx create-expo-app@latest

2

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

Follow the steps below if you have a project that was previously created with Expo but does not have Expo Router library installed.

Prerequisites

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

1

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.

2

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"
}

3

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"
  }
}

4

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'],
  };
};

Note: If your project doesn't have babel.config.js, run npx expo customize babel.config.js to create one.

5

Clear bundler cache

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

Terminal
- npx expo start -c

6

Update resolutions

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 and 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"
  }
}