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

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

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.

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.tsx.

package.json

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

Custom entry point to initialize and load side-effects

You can create a custom entry point in your Expo Router project to initialize and load side-effects before your app loads the root layout (app/_layout.tsx). Below are some of the common cases for a custom entry point:

Initializing global services like analytics, error reporting, and so on.
Setting up polyfills
Ignoring specific logs using LogBox from react-native

Create a new file in the root of your project, such as index.js. After creating this file, the project structure should look like this:

app
_layout.tsx
index.js
package.json
Other project files
Import or add your custom configuration to the file. Then, import expo-router/entry to register the app entry. Remember to always import it last to ensure all configurations are properly set up before the app renders.
index.js
```
// Import side effects first and services

// Initialize services

// Register app entry through Expo Router
import 'expo-router/entry';
```
Update the main property in package.json to point to the new entry file.
package.json
```
{
  "main": "index.js"
}
```

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

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

Clear bundler cache

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

Terminal

- npx expo start --clear

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