1# Expo Router Data Loaders
2 
3Route-level data loading for web apps using Expo SDK 55+. Loaders are async functions exported from route files that load data before the route renders, following the Remix/React Router loader model.
4 
5**Dual execution model:**
6 
7- **Initial page load (SSR):** The loader runs server-side. Its return value is serialized as JSON and embedded in the HTML response.
8- **Client-side navigation:** The browser fetches the loader data from the server via HTTP. The route renders once the data arrives.
9 
10You write one function and the framework manages when and how it executes.
11 
12## Configuration
13 
14**Requirements:** Expo SDK 55+, web output mode (`npx expo serve` or `npx expo export --platform web`) set in `app.json` or `app.config.js`.
15 
16**Server rendering:**
17 
18```json
19{
20  "expo": {
21    "web": {
22      "output": "server"
23    },
24    "plugins": [
25      ["expo-router", {
26        "unstable_useServerDataLoaders": true,
27        "unstable_useServerRendering": true
28      }]
29    ]
30  }
31}
32```
33 
34**Static/SSG:**
35 
36```json
37{
38  "expo": {
39    "web": {
40      "output": "static"
41    },
42    "plugins": [
43      ["expo-router", {
44        "unstable_useServerDataLoaders": true
45      }]
46    ]
47  }
48}
49```
50 
51| | `"server"` | `"static"` |
52|---|-----------|------------|
53| `unstable_useServerDataLoaders` | Required | Required |
54| `unstable_useServerRendering` | Required | Not required |
55| Loader runs on | Live server (every request) | Build time (static generation) |
56| `request` object | Full access (headers, cookies) | Not available |
57| Hosting | Node.js server (EAS Hosting) | Any static host (Netlify, Vercel, S3) |
58 
59## Imports
60 
61Loaders use two packages:
62 
63- **`expo-router`** — `useLoaderData` hook
64- **`expo-server`** — `LoaderFunction` type, `StatusError`, `setResponseHeaders`. Always available (dependency of `expo-router`), no install needed.
65 
66## Basic Loader
67 
68For loaders without params, a plain async function works:
69 
70```tsx
71// app/posts/index.tsx
72import { Suspense } from "react";
73import { useLoaderData } from "expo-router";
74import { ActivityIndicator, View, Text } from "react-native";
75 
76export async function loader() {
77  const response = await fetch("https://api.example.com/posts");
78  const posts = await response.json();
79  return { posts };
80}
81 
82function PostList() {
83  const { posts } = useLoaderData<typeof loader>();
84 
85  return (
86    <View>
87      {posts.map((post) => (
88        <Text key={post.id}>{post.title}</Text>
89      ))}
90    </View>
91  );
92}
93 
94export default function Posts() {
95  return (
96    <Suspense fallback={<ActivityIndicator size="large" />}>
97      <PostList />
98    </Suspense>
99  );
100}
101```
102 
103`useLoaderData` is typed via `typeof loader` — the generic parameter infers the return type.
104 
105## Dynamic Routes
106 
107For loaders with params, use the `LoaderFunction<T>` type from `expo-server`. The first argument is the request (an immutable `Request`-like object, or `undefined` in static mode). The second is `params` (`Record<string, string | string[]>`), which contains **path parameters only**. Access individual params with a cast like `params.id as string`. For query parameters, use `new URL(request.url).searchParams`:
108 
109```tsx
110// app/posts/[id].tsx
111import { Suspense } from "react";
112import { useLoaderData } from "expo-router";
113import { StatusError, type LoaderFunction } from "expo-server";
114import { ActivityIndicator, View, Text } from "react-native";
115 
116type Post = {
117  id: number;
118  title: string;
119  body: string;
120};
121 
122export const loader: LoaderFunction<{ post: Post }> = async (
123  request,
124  params,
125) => {
126  const id = params.id as string;
127  const response = await fetch(`https://api.example.com/posts/${id}`);
128 
129  if (!response.ok) {
130    throw new StatusError(404, `Post ${id} not found`);
131  }
132 
133  const post: Post = await response.json();
134  return { post };
135};
136 
137function PostContent() {
138  const { post } = useLoaderData<typeof loader>();
139 
140  return (
141    <View>
142      <Text>{post.title}</Text>
143      <Text>{post.body}</Text>
144    </View>
145  );
146}
147 
148export default function PostDetail() {
149  return (
150    <Suspense fallback={<ActivityIndicator size="large" />}>
151      <PostContent />
152    </Suspense>
153  );
154}
155```
156 
157Catch-all routes access `params.slug` the same way:
158 
159```tsx
160// app/docs/[...slug].tsx
161import { type LoaderFunction } from "expo-server";
162 
163type Doc = { title: string; content: string };
164 
165export const loader: LoaderFunction<{ doc: Doc }> = async (request, params) => {
166  const slug = params.slug as string[];
167  const path = slug.join("/");
168  const doc = await fetchDoc(path);
169  return { doc };
170};
171```
172 
173Query parameters are available via the `request` object (server output mode only):
174 
175```tsx
176// app/search.tsx
177import { type LoaderFunction } from "expo-server";
178 
179export const loader: LoaderFunction<{ results: any[]; query: string }> = async (request) => {
180  // Assuming request.url is `/search?q=expo&page=2`
181  const url = new URL(request!.url);
182  const query = url.searchParams.get("q") ?? "";
183  const page = Number(url.searchParams.get("page") ?? "1");
184 
185  const results = await fetchSearchResults(query, page);
186  return { results, query };
187};
188```
189 
190## Server-Side Secrets & Request Access
191 
192Loaders run on the server, so you can access secrets and server-only resources directly:
193 
194```tsx
195// app/dashboard.tsx
196import { type LoaderFunction } from "expo-server";
197 
198export const loader: LoaderFunction<{ balance: any; isAuthenticated: boolean }> = async (
199  request,
200  params,
201) => {
202  const data = await fetch("https://api.stripe.com/v1/balance", {
203    headers: {
204      Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
205    },
206  });
207 
208  const sessionToken = request?.headers.get("cookie")?.match(/session=([^;]+)/)?.[1];
209 
210  const balance = await data.json();
211  return { balance, isAuthenticated: !!sessionToken };
212};
213```
214 
215The `request` object is available in server output mode. In static output mode, `request` is always `undefined`.
216 
217## Response Utilities
218 
219### Setting Response Headers
220 
221```tsx
222// app/products.tsx
223import { setResponseHeaders } from "expo-server";
224 
225export async function loader() {
226  setResponseHeaders({
227    "Cache-Control": "public, max-age=300",
228  });
229 
230  const products = await fetchProducts();
231  return { products };
232}
233```
234 
235### Throwing HTTP Errors
236 
237```tsx
238// app/products/[id].tsx
239import { StatusError, type LoaderFunction } from "expo-server";
240 
241export const loader: LoaderFunction<{ product: Product }> = async (request, params) => {
242  const id = params.id as string;
243  const product = await fetchProduct(id);
244 
245  if (!product) {
246    throw new StatusError(404, "Product not found");
247  }
248 
249  return { product };
250};
251```
252 
253## Suspense & Error Boundaries
254 
255### Loading States with Suspense
256 
257`useLoaderData()` suspends during client-side navigation. Push it into a child component and wrap with `<Suspense>`:
258 
259```tsx
260// app/posts/index.tsx
261import { Suspense } from "react";
262import { useLoaderData } from "expo-router";
263import { ActivityIndicator, View, Text } from "react-native";
264 
265export async function loader() {
266  const response = await fetch("https://api.example.com/posts");
267  return { posts: await response.json() };
268}
269 
270function PostList() {
271  const { posts } = useLoaderData<typeof loader>();
272 
273  return (
274    <View>
275      {posts.map((post) => (
276        <Text key={post.id}>{post.title}</Text>
277      ))}
278    </View>
279  );
280}
281 
282export default function Posts() {
283  return (
284    <Suspense
285      fallback={
286        <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
287          <ActivityIndicator size="large" />
288        </View>
289      }
290    >
291      <PostList />
292    </Suspense>
293  );
294}
295```
296 
297The `<Suspense>` boundary must be above the component calling `useLoaderData()`. On initial page load the data is already in the HTML, suspension only occurs during client-side navigation.
298 
299### Error Boundaries
300 
301```tsx
302// app/posts/[id].tsx
303export function ErrorBoundary({ error }: { error: Error }) {
304  return (
305    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
306      <Text>Error: {error.message}</Text>
307    </View>
308  );
309}
310```
311 
312When a loader throws (including `StatusError`), the nearest `ErrorBoundary` catches it.
313 
314## Static vs Server Rendering
315 
316| | Server (`"server"`) | Static (`"static"`) |
317|---|---|---|
318| **When loader runs** | Every request (live) | At build time (`npx expo export`) |
319| **Data freshness** | Fresh on initial server request | Stale until next build |
320| **`request` object** | Full access | Not available |
321| **Hosting** | Node.js server (EAS Hosting) | Any static host |
322| **Use case** | Personalized/dynamic content | Marketing pages, blogs, docs |
323 
324**Choose server** when data changes frequently or content is personalized (cookies, auth, headers).
325 
326**Choose static** when content is the same for all users and changes infrequently.
327 
328## Best Practices
329 
330- Loaders are web-only; use client-side fetching (React Query, fetch) for native
331- Loaders cannot be used in `_layout` files — only in route files
332- Use `LoaderFunction<T>` from `expo-server` to type loaders that use params
333- The request object is immutable — use optional chaining (`request?.headers`) as it may be `undefined` in static mode
334- Return only JSON-serializable values (no `Date`, `Map`, `Set`, class instances, functions)
335- Use non-prefixed `process.env` vars for secrets in loaders, not `EXPO_PUBLIC_` (which is embedded in the client bundle)
336- Use `StatusError` from `expo-server` for HTTP error responses
337- Use `setResponseHeaders` from `expo-server` to set headers
338- Export `ErrorBoundary` from route files to handle loader failures gracefully
339- Validate and sanitize user input (params, query strings) before using in database queries or API calls
340- Handle errors gracefully with try/catch; log server-side for debugging
341- Loader data is currently cached for the session. This is a known limitation that will be lifted in a future release
342