# API Routes

> Server-side endpoints with +api.ts files. See [SKILL.md](../SKILL.md) for decisions, [core.md](core.md) for navigation basics.

---

## Setup

API routes require server output mode in app.json:

```json
{
  "expo": {
    "web": {
      "output": "server"
    },
    "plugins": [
      [
        "expo-router",
        {
          "origin": "https://api.example.com/"
        }
      ]
    ]
  }
}
```

The `origin` property tells native apps where to send API requests. Without it, native API calls have no server to target.

---

## Basic CRUD Routes

```typescript
// app/api/users+api.ts
export async function GET(request: Request) {
  const url = new URL(request.url);
  const page = url.searchParams.get("page") ?? "1";
  const limit = url.searchParams.get("limit") ?? "20";

  const users = await db.users.findMany({
    skip: (Number(page) - 1) * Number(limit),
    take: Number(limit),
  });

  return Response.json(users);
}

export async function POST(request: Request) {
  const body = await request.json();

  const user = await db.users.create({
    data: body,
  });

  return Response.json(user, { status: 201 });
}
```

```typescript
// app/api/users/[id]+api.ts -- Dynamic API route
export async function GET(request: Request, { id }: { id: string }) {
  const user = await db.users.findUnique({ where: { id } });

  if (!user) {
    return new Response("User not found", { status: 404 });
  }

  return Response.json(user);
}

export async function PUT(request: Request, { id }: { id: string }) {
  const body = await request.json();
  const user = await db.users.update({
    where: { id },
    data: body,
  });

  return Response.json(user);
}

export async function DELETE(_request: Request, { id }: { id: string }) {
  await db.users.delete({ where: { id } });
  return new Response(null, { status: 204 });
}
```

---

## Error Handling with StatusError

```typescript
// app/api/posts+api.ts
import { StatusError } from "expo-server";

export async function GET(request: Request) {
  const url = new URL(request.url);
  const postId = url.searchParams.get("id");

  if (!postId) {
    throw new StatusError(400, "Missing required parameter: id");
  }

  const post = await db.posts.findUnique({ where: { id: postId } });

  if (!post) {
    throw new StatusError(404, "Post not found");
  }

  return Response.json(post);
}
```

---

## Secure API Route (Token Validation)

```typescript
// app/api/protected+api.ts

const BEARER_PREFIX = "Bearer ";

function getAuthToken(request: Request): string | null {
  const auth = request.headers.get("Authorization");
  if (!auth?.startsWith(BEARER_PREFIX)) return null;
  return auth.slice(BEARER_PREFIX.length);
}

export async function GET(request: Request) {
  const token = getAuthToken(request);

  if (!token) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const user = await validateToken(token);
  if (!user) {
    return Response.json({ error: "Invalid token" }, { status: 403 });
  }

  return Response.json({ user });
}
```

---

## Background Tasks (SDK 54+)

```typescript
// app/api/webhook+api.ts
import { runTask, deferTask } from "expo-server";

export async function POST(request: Request) {
  const payload = await request.json();

  // runTask: executes concurrently, response waits for completion
  await runTask(async () => {
    await processWebhookPayload(payload);
  });

  // deferTask: executes AFTER response is sent to client
  deferTask(async () => {
    await sendNotification(payload.userId);
  });

  return Response.json({ received: true });
}
```

---

## Key Limitations

- **No dynamic imports** -- external deps with platform binaries cannot be bundled
- **Bundles to CommonJS** -- ESM syntax is recommended but transpiles to CJS
- **No platform-specific extensions** -- `users+api.web.ts` does not work
- **Environment variables** -- non-public env vars (without `EXPO_PUBLIC_` prefix) are accessible since these run server-side
- **Deployment** -- use `npx expo export --platform web` and deploy the `dist/` directory

# Authentication Patterns

> Route protection and auth flows. See [SKILL.md](../SKILL.md) for decisions, [core.md](core.md) for navigation basics.

---

## Stack.Protected Pattern (SDK 53+ -- Recommended)

### Session Provider

```typescript
// ctx.tsx -- Authentication context
import { use, createContext, type PropsWithChildren } from "react";
import { useStorageState } from "./use-storage-state";

interface AuthContextValue {
  signIn: (token: string) => void;
  signOut: () => void;
  session: string | null;
  isLoading: boolean;
}

const AuthContext = createContext<AuthContextValue | null>(null);

export function useSession(): AuthContextValue {
  const value = use(AuthContext);
  if (!value) {
    throw new Error("useSession must be wrapped in a <SessionProvider />");
  }
  return value;
}

export function SessionProvider({ children }: PropsWithChildren) {
  const [[isLoading, session], setSession] = useStorageState("session");

  return (
    <AuthContext
      value={{
        signIn: (token: string) => setSession(token),
        signOut: () => setSession(null),
        session,
        isLoading,
      }}
    >
      {children}
    </AuthContext>
  );
}
```

### Root Layout with Stack.Protected

```typescript
// app/_layout.tsx
import { Stack } from "expo-router";
import * as SplashScreen from "expo-splash-screen";
import { SessionProvider, useSession } from "../ctx";

SplashScreen.preventAutoHideAsync();

export default function Root() {
  return (
    <SessionProvider>
      <SplashScreenController />
      <RootNavigator />
    </SessionProvider>
  );
}

function SplashScreenController() {
  const { isLoading } = useSession();
  if (!isLoading) {
    SplashScreen.hide();
  }
  return null;
}

function RootNavigator() {
  const { session } = useSession();

  return (
    <Stack>
      {/* Protected routes -- only accessible when session exists */}
      <Stack.Protected guard={!!session}>
        <Stack.Screen name="(app)" options={{ headerShown: false }} />
      </Stack.Protected>

      {/* Public routes -- only accessible when no session */}
      <Stack.Protected guard={!session}>
        <Stack.Screen name="sign-in" options={{ headerShown: false }} />
      </Stack.Protected>
    </Stack>
  );
}
```

### Directory Structure

```
app/
├── _layout.tsx          # Root with Stack.Protected
├── sign-in.tsx          # Public sign-in screen
└── (app)/               # Protected group
    ├── _layout.tsx      # App layout (tabs, etc.)
    ├── index.tsx         # Home screen
    └── profile.tsx       # Profile screen
```

### Sign-In Screen

```typescript
// app/sign-in.tsx
import { router } from "expo-router";
import { View, Text, Pressable, TextInput, StyleSheet } from "react-native";
import { useState } from "react";
import { useSession } from "../ctx";

export default function SignIn() {
  const { signIn } = useSession();
  const [email, setEmail] = useState("");

  const handleSignIn = async () => {
    // Your auth logic here (API call, etc.)
    const token = await authenticateUser(email);
    signIn(token);
    router.replace("/"); // Navigate to protected home
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Sign In</Text>
      <TextInput
        style={styles.input}
        placeholder="Email"
        value={email}
        onChangeText={setEmail}
        autoCapitalize="none"
      />
      <Pressable style={styles.button} onPress={handleSignIn}>
        <Text style={styles.buttonText}>Sign In</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", padding: 16 },
  title: { fontSize: 24, fontWeight: "bold", marginBottom: 24, textAlign: "center" },
  input: { borderWidth: 1, borderColor: "#ccc", padding: 12, borderRadius: 8, marginBottom: 16 },
  button: { backgroundColor: "#007AFF", padding: 16, borderRadius: 8, alignItems: "center" },
  buttonText: { color: "#fff", fontWeight: "600", fontSize: 16 },
});
```

---

## How Stack.Protected Guard Works

```
User authenticated (session exists):
  guard={!!session} -> true  -> (app) screens accessible
  guard={!session}  -> false -> sign-in screen hidden

User not authenticated (no session):
  guard={!!session} -> false -> (app) screens hidden
  guard={!session}  -> true  -> sign-in screen accessible

User navigates to protected route while unauthenticated:
  -> Automatically redirected to first available unprotected screen (sign-in)

User signs out while on protected screen:
  -> guard flips to false -> redirected to sign-in automatically
```

---

## Modal Sign-In Pattern (Alternative)

For apps where you want the main content visible behind a sign-in overlay:

```typescript
// app/_layout.tsx
import { Stack } from "expo-router";

export const unstable_settings = {
  initialRouteName: "(root)",
};

export default function AppLayout() {
  return (
    <Stack>
      <Stack.Screen name="(root)" options={{ headerShown: false }} />
      <Stack.Screen
        name="sign-in"
        options={{
          presentation: "modal",
          // Prevent dismissing the modal without signing in
          gestureEnabled: false,
          headerShown: false,
        }}
      />
    </Stack>
  );
}
```

**Trade-off:** Modal sign-in preserves deep links better (the target route is already loaded behind the modal), but requires more careful handling of the unauthenticated state since routes render in the background.

---

## Legacy Redirect Pattern (SDK 52 and Earlier)

For projects not yet on SDK 53, use the `Redirect` component in a layout:

```typescript
// app/(app)/_layout.tsx
import { Redirect, Stack } from "expo-router";
import { Text } from "react-native";
import { useSession } from "../../ctx";

export default function AppLayout() {
  const { session, isLoading } = useSession();

  if (isLoading) {
    return <Text>Loading...</Text>;
  }

  if (!session) {
    return <Redirect href="/sign-in" />;
  }

  return <Stack />;
}
```

**Why Stack.Protected is better:** The Redirect approach renders the protected layout momentarily before redirecting. Stack.Protected prevents the screen from rendering at all when guard is false.

# Expo Router Core Patterns

> Layouts, tabs, navigation hooks, dynamic routes, modals, typed routes. See [SKILL.md](../SKILL.md) for decisions and philosophy.

---

## Directory Structure

```
app/
├── _layout.tsx              # Root layout (Stack navigator)
├── index.tsx                # Home route (/)
├── about.tsx                # /about
├── +not-found.tsx           # 404 fallback
├── modal.tsx                # /modal (configured as modal in root layout)
├── settings/
│   ├── _layout.tsx          # Settings stack layout
│   ├── index.tsx            # /settings
│   └── profile.tsx          # /settings/profile
├── users/
│   ├── _layout.tsx          # Users layout
│   ├── index.tsx            # /users
│   └── [id].tsx             # /users/:id (dynamic)
├── docs/
│   └── [...slug].tsx        # /docs/a/b/c (catch-all)
├── (tabs)/                  # Tab navigator (group -- not in URL)
│   ├── _layout.tsx          # Tab layout
│   ├── home.tsx             # Tab: home
│   ├── search.tsx           # Tab: search
│   └── profile.tsx          # Tab: profile
└── api/
    └── users+api.ts         # API route: /api/users
```

---

## Root Layout with Stack

```typescript
// app/_layout.tsx
import { Stack } from "expo-router";

export default function RootLayout() {
  return (
    <Stack>
      <Stack.Screen name="index" options={{ title: "Home" }} />
      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
      <Stack.Screen name="settings" options={{ title: "Settings" }} />
      <Stack.Screen
        name="modal"
        options={{
          presentation: "modal",
          headerShown: true,
          title: "Modal",
        }}
      />
      <Stack.Screen name="+not-found" />
    </Stack>
  );
}
```

---

## Tab Navigation

```typescript
// app/(tabs)/_layout.tsx
import { Tabs } from "expo-router";

const TAB_ICON_SIZE = 24;

export default function TabLayout() {
  return (
    <Tabs
      screenOptions={{
        tabBarActiveTintColor: "#007AFF",
        tabBarInactiveTintColor: "#8E8E93",
        headerShown: true,
      }}
    >
      <Tabs.Screen
        name="home"
        options={{
          title: "Home",
          tabBarIcon: ({ color }) => <IconComponent name="home" size={TAB_ICON_SIZE} color={color} />,
        }}
      />
      <Tabs.Screen
        name="search"
        options={{
          title: "Search",
          tabBarIcon: ({ color }) => <IconComponent name="search" size={TAB_ICON_SIZE} color={color} />,
        }}
      />
      <Tabs.Screen
        name="profile"
        options={{
          title: "Profile",
          tabBarIcon: ({ color }) => <IconComponent name="person" size={TAB_ICON_SIZE} color={color} />,
        }}
      />
    </Tabs>
  );
}
```

---

## Nested Stack Inside Tabs

```
app/
├── (tabs)/
│   ├── _layout.tsx           # Tab navigator
│   ├── feed/
│   │   ├── _layout.tsx       # Stack navigator for feed tab
│   │   ├── index.tsx         # Feed list (/feed)
│   │   └── [postId].tsx      # Post detail (/feed/:postId)
│   └── settings.tsx          # Settings tab
```

```typescript
// app/(tabs)/feed/_layout.tsx
import { Stack } from "expo-router";

export default function FeedLayout() {
  return (
    <Stack>
      <Stack.Screen name="index" options={{ title: "Feed" }} />
      <Stack.Screen
        name="[postId]"
        options={{ title: "Post", headerBackTitle: "Feed" }}
      />
    </Stack>
  );
}

// app/(tabs)/feed/[postId].tsx
import { useLocalSearchParams, Stack } from "expo-router";
import { View, Text, StyleSheet } from "react-native";

export default function PostDetailScreen() {
  const { postId } = useLocalSearchParams<{ postId: string }>();

  return (
    <>
      {/* Dynamic screen options -- overrides layout config */}
      <Stack.Screen options={{ title: `Post ${postId}` }} />
      <View style={styles.container}>
        <Text style={styles.title}>Post {postId}</Text>
      </View>
    </>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 16 },
  title: { fontSize: 24, fontWeight: "bold" },
});
```

---

## Navigation Hooks Usage

```typescript
// components/navigation-example.tsx
import {
  useRouter,
  useLocalSearchParams,
  usePathname,
  useSegments,
  Link,
} from "expo-router";
import { View, Text, Pressable, StyleSheet } from "react-native";

export function NavigationExample() {
  const router = useRouter();
  const { id } = useLocalSearchParams<{ id: string }>();
  const pathname = usePathname();
  const segments = useSegments();

  const handlePush = () => {
    router.push("/users/123");
  };

  const handlePushWithParams = () => {
    // Object form for typed routes
    router.push({
      pathname: "/users/[id]",
      params: { id: "456" },
    });
  };

  const handleReplace = () => {
    // Replace -- no back button to return
    router.replace("/home");
  };

  const handleDismiss = () => {
    // Dismiss modal or pop stack screen
    if (router.canDismiss()) {
      router.dismissTo("/home");
    }
  };

  return (
    <View style={styles.container}>
      {/* Declarative navigation -- preferred for static links */}
      <Link href="/about" style={styles.link}>
        <Text>About</Text>
      </Link>

      {/* Link with asChild -- passes navigation behavior to child */}
      <Link href="/users/123" asChild>
        <Pressable style={styles.button}>
          <Text style={styles.buttonText}>User Profile</Text>
        </Pressable>
      </Link>

      {/* Link with params object */}
      <Link
        href={{ pathname: "/search", params: { query: "expo" } }}
        style={styles.link}
      >
        <Text>Search for Expo</Text>
      </Link>

      {/* Imperative navigation */}
      <Pressable style={styles.button} onPress={handlePush}>
        <Text style={styles.buttonText}>Push Screen</Text>
      </Pressable>

      <Text style={styles.info}>Path: {pathname}</Text>
      <Text style={styles.info}>Segments: {segments.join("/")}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 16, gap: 12 },
  link: { padding: 12, backgroundColor: "#f0f0f0", borderRadius: 8 },
  button: { padding: 12, backgroundColor: "#007AFF", borderRadius: 8, alignItems: "center" },
  buttonText: { color: "#fff", fontWeight: "600" },
  info: { fontSize: 12, color: "#666" },
});
```

---

## Dynamic Route

```typescript
// app/users/[id].tsx
import { useLocalSearchParams, Stack } from "expo-router";
import { View, Text } from "react-native";

export default function UserScreen() {
  const { id } = useLocalSearchParams<{ id: string }>();

  return (
    <>
      <Stack.Screen options={{ title: `User ${id}` }} />
      <View style={{ flex: 1, padding: 16 }}>
        <Text>User ID: {id}</Text>
      </View>
    </>
  );
}
```

---

## Catch-All Route

```typescript
// app/docs/[...slug].tsx
import { useLocalSearchParams } from "expo-router";
import { View, Text } from "react-native";

export default function DocsScreen() {
  const { slug } = useLocalSearchParams<{ slug: string[] }>();

  // IMPORTANT: Normalize -- single segment returns string, multiple returns array
  const segments = Array.isArray(slug) ? slug : [slug];
  const path = segments.join("/");

  return (
    <View style={{ flex: 1, padding: 16 }}>
      <Text>Docs path: {path}</Text>
      <Text>Depth: {segments.length} levels</Text>
    </View>
  );
}
```

---

## Modal Route

```typescript
// app/modal.tsx -- the file itself is a regular route
import { useRouter } from "expo-router";
import { View, Text, Pressable, StyleSheet } from "react-native";

export default function ModalScreen() {
  const router = useRouter();

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Modal Content</Text>
      <Pressable style={styles.closeButton} onPress={() => router.back()}>
        <Text style={styles.closeText}>Close</Text>
      </Pressable>
    </View>
  );
}

// The modal PRESENTATION is configured in the PARENT layout:
// app/_layout.tsx -> <Stack.Screen name="modal" options={{ presentation: "modal" }} />

const styles = StyleSheet.create({
  container: { flex: 1, padding: 16, alignItems: "center", justifyContent: "center" },
  title: { fontSize: 24, fontWeight: "bold", marginBottom: 16 },
  closeButton: { padding: 12, backgroundColor: "#007AFF", borderRadius: 8 },
  closeText: { color: "#fff", fontWeight: "600" },
});
```

---

## Form Sheet (iOS)

```typescript
// Configure in parent layout
<Stack.Screen
  name="sheet"
  options={{
    presentation: "formSheet",
    sheetGrabberVisible: true,
    sheetCornerRadius: 16,
    // Optional: control sheet height
    // sheetInitialDetentIndex: 0,
    // sheetAllowedDetents: [0.5, 1.0],
  }}
/>
```

---

## Shared Routes Between Tab Groups

When multiple tabs need to show the same screen (e.g., a user profile accessible from both feed and search):

```
app/(tabs)/
├── _layout.tsx
├── (feed)/
│   └── index.tsx            # Feed tab content
├── (search)/
│   └── search.tsx           # Search tab content
└── (feed,search)/           # Shared between both groups
    ├── _layout.tsx
    └── users/
        └── [username].tsx   # Accessible from both feed and search
```

```typescript
// app/(tabs)/(feed,search)/users/[username].tsx
import { useLocalSearchParams } from "expo-router";
import { View, Text, StyleSheet } from "react-native";

export default function UserProfileScreen() {
  const { username } = useLocalSearchParams<{ username: string }>();

  return (
    <View style={styles.container}>
      <Text style={styles.title}>@{username}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 16 },
  title: { fontSize: 24, fontWeight: "bold" },
});
```

---

## Headless Tabs (Custom Tab Bar UI)

When the default tab bar doesn't fit your design, use headless tab components from `expo-router/ui` for full control over rendering:

```typescript
// app/(tabs)/_layout.tsx
import { Tabs, TabList, TabTrigger, TabSlot } from "expo-router/ui";
import { Text, StyleSheet } from "react-native";

const TAB_BAR_HEIGHT = 60;

export default function CustomTabLayout() {
  return (
    <Tabs>
      {/* Content area -- renders the active tab's content */}
      <TabSlot />

      {/* Fully custom tab bar */}
      <TabList style={styles.tabBar}>
        <TabTrigger name="home" href="/" style={styles.tab}>
          <Text>Home</Text>
        </TabTrigger>
        <TabTrigger name="search" href="/search" style={styles.tab}>
          <Text>Search</Text>
        </TabTrigger>
        <TabTrigger name="profile" href="/profile" style={styles.tab}>
          <Text>Profile</Text>
        </TabTrigger>
      </TabList>
    </Tabs>
  );
}

const styles = StyleSheet.create({
  tabBar: {
    flexDirection: "row",
    height: TAB_BAR_HEIGHT,
    backgroundColor: "#fff",
    borderTopWidth: 1,
    borderTopColor: "#e0e0e0",
  },
  tab: { flex: 1, alignItems: "center", justifyContent: "center" },
});
```

---

## Typed Routes Setup

```json
// app.json
{
  "expo": {
    "experiments": {
      "typedRoutes": true
    }
  }
}
```

```typescript
// After enabling and starting dev server, routes are auto-typed:
import { useRouter, useLocalSearchParams, Link } from "expo-router";

export function TypedNavigationExample() {
  const router = useRouter();

  // TypeScript validates route exists
  router.push("/about");

  // TypeScript requires correct params for dynamic routes
  router.push({ pathname: "/users/[id]", params: { id: "123" } });

  // TypeScript errors on invalid routes
  // router.push("/nonexistent"); // Error!

  // Typed params from route
  const { id } = useLocalSearchParams<"/users/[id]">();
  // id is typed as string

  // Typed Link
  return <Link href={{ pathname: "/users/[id]", params: { id: "456" } }}>User</Link>;
}
```

---

## 404 Not Found Route

```typescript
// app/+not-found.tsx
import { Link, Stack } from "expo-router";
import { View, Text, StyleSheet } from "react-native";

export default function NotFoundScreen() {
  return (
    <>
      <Stack.Screen options={{ title: "Not Found" }} />
      <View style={styles.container}>
        <Text style={styles.title}>This screen does not exist.</Text>
        <Link href="/" style={styles.link}>
          <Text style={styles.linkText}>Go to home screen</Text>
        </Link>
      </View>
    </>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, alignItems: "center", justifyContent: "center", padding: 20 },
  title: { fontSize: 20, fontWeight: "bold" },
  link: { marginTop: 16, paddingVertical: 16 },
  linkText: { fontSize: 14, color: "#2e78b7" },
});
```

---

## useFocusEffect for Data Fetching

```typescript
// Fetch data when screen comes into focus (e.g., returning from edit screen)
import { useFocusEffect } from "expo-router";
import { useCallback, useState } from "react";

export default function UserListScreen() {
  const [users, setUsers] = useState([]);

  useFocusEffect(
    useCallback(() => {
      // Runs on focus, cleanup on blur
      let isActive = true;

      async function fetchUsers() {
        const data = await getUsers();
        if (isActive) setUsers(data);
      }

      fetchUsers();

      return () => {
        isActive = false; // Prevent state update after blur
      };
    }, []),
  );

  // Render users...
}
```

# Web: Static Rendering and Head Metadata

> Static rendering, SEO, and head metadata for web output. See [SKILL.md](../SKILL.md) for decisions, [core.md](core.md) for navigation basics.

---

## Enabling Static Rendering

```json
// app.json
{
  "expo": {
    "web": {
      "output": "static"
    }
  }
}
```

Static rendering generates individual HTML files at build time. Each route becomes a separate `.html` file for SEO and fast initial loads.

```bash
# Development
npx expo start

# Production export
npx expo export --platform web
# Generates dist/ directory -- deploy to any static host
```

---

## Head Metadata

Use the `Head` component from `expo-router/head` to manage `<title>` and `<meta>` tags per page:

```typescript
// app/about.tsx
import Head from "expo-router/head";
import { Text, View, StyleSheet } from "react-native";

export default function AboutPage() {
  return (
    <>
      <Head>
        <title>About Us | MyApp</title>
        <meta name="description" content="Learn about our mission and team." />
        <meta property="og:title" content="About Us" />
        <meta property="og:description" content="Learn about our mission." />
      </Head>
      <View style={styles.container}>
        <Text style={styles.heading}>About Us</Text>
      </View>
    </>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 16 },
  heading: { fontSize: 32, fontWeight: "bold" },
});
```

**Note:** `Head` renders on web only. On native platforms, it is a no-op. This is safe to include in universal components.

---

## Dynamic Head Metadata

```typescript
// app/posts/[id].tsx
import Head from "expo-router/head";
import { useLocalSearchParams } from "expo-router";
import { Text, View } from "react-native";

export default function PostPage() {
  const { id } = useLocalSearchParams<{ id: string }>();
  // In a real app, fetch post data based on id
  const title = `Post ${id}`;

  return (
    <>
      <Head>
        <title>{title} | MyBlog</title>
        <meta name="description" content={`Read post ${id}`} />
      </Head>
      <View style={{ flex: 1, padding: 16 }}>
        <Text>{title}</Text>
      </View>
    </>
  );
}
```

---

## generateStaticParams for Dynamic Routes

Dynamic routes (`[id].tsx`) require `generateStaticParams` to pre-render pages at build time. Without it, dynamic routes are not included in the static output.

```typescript
// app/posts/[id].tsx
import { useLocalSearchParams } from "expo-router";
import Head from "expo-router/head";
import { Text, View } from "react-native";

// Runs at BUILD TIME in Node.js -- no React Native APIs available
export async function generateStaticParams(): Promise<Record<string, string>[]> {
  const posts = await fetchAllPosts(); // API call, file read, etc.
  return posts.map((post) => ({ id: post.id }));
  // Generates: /posts/1.html, /posts/2.html, ...
}

export default function PostPage() {
  const { id } = useLocalSearchParams<{ id: string }>();

  return (
    <>
      <Head>
        <title>Post {id}</title>
      </Head>
      <View style={{ flex: 1, padding: 16 }}>
        <Text>Post {id}</Text>
      </View>
    </>
  );
}
```

**Key constraint:** `generateStaticParams` runs in Node.js during the build. It can access `process.cwd()`, environment variables, and the filesystem -- but NOT browser APIs, React Native APIs, or native modules.

---

## Root HTML Customization

Create `app/+html.tsx` to customize the HTML wrapper for all pages. This runs in Node.js only.

```typescript
// app/+html.tsx
import { ScrollViewStyleReset } from "expo-router/html";
import type { PropsWithChildren } from "react";

export default function Root({ children }: PropsWithChildren) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
        {/* ScrollViewStyleReset prevents overflow issues with React Native Web */}
        <ScrollViewStyleReset />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

---

## Static vs Server Output

| Feature                 | `"static"`                            | `"server"`                             |
| ----------------------- | ------------------------------------- | -------------------------------------- |
| Output                  | Individual `.html` files              | Server bundle + client bundle          |
| Dynamic routes          | Requires `generateStaticParams`       | Rendered on request                    |
| API routes (`+api.ts`)  | Not available                         | Available                              |
| Deployment              | Any static host (Netlify, Vercel, S3) | Requires server (EAS Hosting, Node.js) |
| SEO                     | Excellent (pre-rendered HTML)         | Good (SSR on request)                  |
| React Server Components | No                                    | Yes (experimental)                     |

Choose `"static"` for content sites, marketing pages, and blogs. Choose `"server"` when you need API routes, dynamic server-rendered pages, or React Server Components.