Skip to main content

​
Installation

This guide covers installing Expo Router and its required dependencies in your project.

​
Prerequisites

  • Node.js 18 or later
  • Expo CLI
  • An Expo project (SDK 52 or later recommended)

​
Automatic Installation

The easiest way to get started is to use create-expo-app with the default template: 
npx create-expo-app@latest my-app
cd my-app
This automatically sets up Expo Router with all required dependencies.

​
Manual Installation

If you have an existing Expo project, install Expo Router and its dependencies: 
npm install expo-router

​
Required Dependencies

Expo Router requires these peer dependencies: 
npx expo install expo-linking expo-constants expo-status-bar \
  react-native-safe-area-context react-native-screens

​
Optional Dependencies

For additional navigation features: 
# For drawer navigation
npx expo install react-native-gesture-handler react-native-reanimated \
  @react-navigation/drawer

# For web support
npm install react-dom react-native-web

​
Project Setup

​
1. Update Entry Point

Modify your package.json to use Expo Router’s entry point:
package.json
{
  "main": "expo-router/entry"
}

​
2. Add Expo Router Plugin

Update your app.json or app.config.js:
app.json
{
  "expo": {
    "scheme": "myapp",
    "plugins": ["expo-router"]
  }
}
For app.config.js:
app.config.js
export default {
  expo: {
    scheme: 'myapp',
    plugins: ['expo-router'],
  },
};
The scheme is required for deep linking. Choose a unique scheme for your app.

​
3. Modify TypeScript Config

If using TypeScript, extend the Expo Router TypeScript config in tsconfig.json:
tsconfig.json
{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "strict": true
  }
}

​
4. Configure Metro Bundler

Create or update metro.config.js:
metro.config.js
const { getDefaultConfig } = require('expo/metro-config');

const config = getDefaultConfig(__dirname);

module.exports = config;

​
5. Clear Cache

After installation, clear the Metro bundler cache: 
npx expo start --clear

​
Project Structure

Create the app directory in your project root: 
my-app/
  app/
    _layout.tsx
    index.tsx
  package.json
  app.json

​
Verify Installation

Create a simple layout and index file to verify everything works:
app/_layout.tsx
import { Stack } from 'expo-router';

export default function Layout() {
  return <Stack />;
}
app/index.tsx
import { View, Text } from 'react-native';

export default function Home() {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>Welcome to Expo Router!</Text>
    </View>
  );
}
Start your development server: 
npx expo start
Press i for iOS simulator, a for Android emulator, or w for web.

​
Platform-Specific Setup

​
iOS

For iOS, run: 
cd ios && pod install && cd ..
Or if using Expo Go: 
npx expo run:ios

​
Android

For Android: 
npx expo run:android

​
Web

For web development: 
npx expo start --web

​
Troubleshooting

​
Metro Bundler Issues

If you encounter caching issues: 
npx expo start --clear
# or
rm -rf node_modules/.cache

​
Type Errors

If TypeScript doesn’t recognize routes: 
rm -rf node_modules/.cache
npx expo start
Expo Router generates types automatically when the dev server starts.

​
Deep Linking Not Working

Ensure your scheme is set in app.json:
app.json
{
  "expo": {
    "scheme": "myapp"
  }
}

​
React Native Screens

If navigation isn’t working properly:
  1. Ensure react-native-screens is installed
  2. For bare React Native apps, follow the react-native-screens installation guide
  3. Rebuild your app after installing native dependencies

​
Next Steps

Quick Start

Build your first app with Expo Router

File-Based Routing

Learn routing conventions