Installation

Install Expo Router and configure your project for file-based routing

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

npm install expo-router

yarn

yarn add expo-router

pnpm

pnpm add expo-router

Required Dependencies

Expo Router requires these peer dependencies:

npm

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

yarn

yarn expo install expo-linking expo-constants expo-status-bar \
  react-native-safe-area-context react-native-screens

pnpm

pnpm expo install expo-linking expo-constants expo-status-bar \
  react-native-safe-area-context react-native-screens

Optional Dependencies

For additional navigation features:

npm

# 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

yarn

# For drawer navigation
yarn expo install react-native-gesture-handler react-native-reanimated \
  @react-navigation/drawer

# For web support
yarn add 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