---
name: expo-router
user-invocable: false
description: Use when implementing file-based routing in Expo with Expo Router. Covers app directory structure, navigation, layouts, dynamic routes, and deep linking.
allowed-tools:
- Read
- Write
- Edit
- Bash
- Grep
- Glob
---
# Expo Router
Use this skill when implementing file-based routing with Expo Router, the recommended navigation solution for Expo apps.
## Key Concepts
### File-Based Routing
Routes are defined by file structure:
```
app/
_layout.tsx # Root layout
index.tsx # / route
about.tsx # /about route
(tabs)/ # Group (not in URL)
_layout.tsx # Tabs layout
home.tsx # /home
profile.tsx # /profile
users/
[id].tsx # /users/:id dynamic route
index.tsx # /users route
```
### Basic Routes
```tsx
// app/index.tsx
import { View, Text } from 'react-native';
import { Link } from 'expo-router';
export default function Home() {
return (
Home Screen
Go to About
);
}
// app/about.tsx
export default function About() {
return (
About Screen
);
}
```
### Layouts
```tsx
// app/_layout.tsx
import { Stack } from 'expo-router';
export default function RootLayout() {
return (
);
}
```
### Tab Navigation
```tsx
// app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
import { Ionicons } from '@expo/vector-icons';
export default function TabLayout() {
return (
(
),
}}
/>
(
),
}}
/>
);
}
```
## Best Practices
### Dynamic Routes
```tsx
// app/users/[id].tsx
import { useLocalSearchParams } from 'expo-router';
import { View, Text } from 'react-native';
export default function UserDetails() {
const { id } = useLocalSearchParams<{ id: string }>();
return (
User ID: {id}
);
}
// Navigate to /users/123
View User
// Or
import { router } from 'expo-router';
router.push('/users/123');
```
### Programmatic Navigation
```tsx
import { router } from 'expo-router';
function MyComponent() {
const handlePress = () => {
// Navigate to route
router.push('/details');
// Navigate with params
router.push({
pathname: '/users/[id]',
params: { id: '123' },
});
// Replace current route
router.replace('/login');
// Go back
router.back();
};
return ;
}
```
### Type-Safe Routes
```tsx
// types/navigation.ts
export type RootStackParamList = {
'/': undefined;
'/about': undefined;
'/users/[id]': { id: string };
'/posts/[id]': { id: string; title?: string };
};
// Usage with type safety
import { router } from 'expo-router';
import type { RootStackParamList } from './types/navigation';
// TypeScript will enforce correct params
router.push({
pathname: '/users/[id]' as const,
params: { id: '123' },
});
```
### Route Groups
Group routes without affecting URLs:
```
app/
(auth)/ # Group (not in URL)
login.tsx # /login
register.tsx # /register
_layout.tsx # Auth layout
(app)/ # Group (not in URL)
home.tsx # /home
profile.tsx # /profile
_layout.tsx # App layout
```
```tsx
// app/(auth)/_layout.tsx
import { Stack } from 'expo-router';
export default function AuthLayout() {
return (
);
}
```
## Common Patterns
### Authentication Flow
```tsx
// app/_layout.tsx
import { Slot, useRouter, useSegments } from 'expo-router';
import { useEffect } from 'react';
import { useAuth } from './hooks/useAuth';
export default function RootLayout() {
const { user, loading } = useAuth();
const segments = useSegments();
const router = useRouter();
useEffect(() => {
if (loading) return;
const inAuthGroup = segments[0] === '(auth)';
if (!user && !inAuthGroup) {
router.replace('/(auth)/login');
} else if (user && inAuthGroup) {
router.replace('/(app)/home');
}
}, [user, loading, segments]);
return ;
}
```
### Modal Routes
```tsx
// app/_layout.tsx
import { Stack } from 'expo-router';
export default function RootLayout() {
return (
);
}
// app/modal.tsx
import { View, Text, Button } from 'react-native';
import { router } from 'expo-router';
export default function Modal() {
return (
Modal Content
);
}
```
### Deep Linking
```json
// app.json
{
"expo": {
"scheme": "myapp",
"plugins": ["expo-router"]
}
}
```
```tsx
// Deep link: myapp://users/123
// Opens app/users/[id].tsx with id="123"
// Universal link: https://myapp.com/users/123
// Requires additional iOS/Android configuration
```
### Search Params
```tsx
import { useLocalSearchParams } from 'expo-router';
function ProductScreen() {
const { id, category, sort } = useLocalSearchParams<{
id: string;
category?: string;
sort?: string;
}>();
return (
Product: {id}
Category: {category}
Sort: {sort}
);
}
// Navigate with query params
View Product
```
## Anti-Patterns
### Don't Use React Navigation Directly
```tsx
// Bad - Mixing Expo Router with React Navigation
import { NavigationContainer } from '@react-navigation/native';
// Good - Use Expo Router only
import { Stack } from 'expo-router';
```
### Don't Nest Navigators Incorrectly
```tsx
// Bad - Multiple Stack navigators without layout
// app/home.tsx
// Good - Use layouts for nested navigation
// app/home/_layout.tsx
```
### Don't Hardcode Routes
```tsx
// Bad - String literals everywhere
router.push('/users/123');
router.push('/prodcts/456'); // Typo won't be caught
// Good - Use constants or typed routes
const ROUTES = {
USER_DETAILS: (id: string) => `/users/${id}` as const,
PRODUCT_DETAILS: (id: string) => `/products/${id}` as const,
} as const;
router.push(ROUTES.USER_DETAILS('123'));
```
## Related Skills
- **expo-config**: Configuring deep linking
- **expo-modules**: Using navigation with Expo modules