> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/expo/expo/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install expo-router
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add expo-router
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add expo-router
    ```
  </Tab>
</Tabs>

### Required Dependencies

Expo Router requires these peer dependencies:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npx expo install expo-linking expo-constants expo-status-bar \
      react-native-safe-area-context react-native-screens
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn expo install expo-linking expo-constants expo-status-bar \
      react-native-safe-area-context react-native-screens
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm expo install expo-linking expo-constants expo-status-bar \
      react-native-safe-area-context react-native-screens
    ```
  </Tab>
</Tabs>

### Optional Dependencies

For additional navigation features:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

## Project Setup

### 1. Update Entry Point

Modify your `package.json` to use Expo Router's entry point:

```json package.json theme={null}
{
  "main": "expo-router/entry"
}
```

### 2. Add Expo Router Plugin

Update your `app.json` or `app.config.js`:

```json app.json theme={null}
{
  "expo": {
    "scheme": "myapp",
    "plugins": ["expo-router"]
  }
}
```

For `app.config.js`:

```js app.config.js theme={null}
export default {
  expo: {
    scheme: 'myapp',
    plugins: ['expo-router'],
  },
};
```

<Note>
  The `scheme` is required for deep linking. Choose a unique scheme for your app.
</Note>

### 3. Modify TypeScript Config

If using TypeScript, extend the Expo Router TypeScript config in `tsconfig.json`:

```json tsconfig.json theme={null}
{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "strict": true
  }
}
```

### 4. Configure Metro Bundler

Create or update `metro.config.js`:

```js metro.config.js theme={null}
const { getDefaultConfig } = require('expo/metro-config');

const config = getDefaultConfig(__dirname);

module.exports = config;
```

### 5. Clear Cache

After installation, clear the Metro bundler cache:

```bash theme={null}
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:

```tsx app/_layout.tsx theme={null}
import { Stack } from 'expo-router';

export default function Layout() {
  return <Stack />;
}
```

```tsx app/index.tsx theme={null}
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:

```bash theme={null}
npx expo start
```

Press `i` for iOS simulator, `a` for Android emulator, or `w` for web.

## Platform-Specific Setup

### iOS

For iOS, run:

```bash theme={null}
cd ios && pod install && cd ..
```

Or if using Expo Go:

```bash theme={null}
npx expo run:ios
```

### Android

For Android:

```bash theme={null}
npx expo run:android
```

### Web

For web development:

```bash theme={null}
npx expo start --web
```

## Troubleshooting

### Metro Bundler Issues

If you encounter caching issues:

```bash theme={null}
npx expo start --clear
# or
rm -rf node_modules/.cache
```

### Type Errors

If TypeScript doesn't recognize routes:

```bash theme={null}
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`:

```json app.json theme={null}
{
  "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](https://github.com/software-mansion/react-native-screens)
3. Rebuild your app after installing native dependencies

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/router/quick-start">
    Build your first app with Expo Router
  </Card>

  <Card title="File-Based Routing" icon="folder" href="/router/file-based-routing">
    Learn routing conventions
  </Card>
</CardGroup>