1---
2name: expo-api-routes
3description: Guidelines for creating API routes in Expo Router with EAS Hosting
4version: 1.0.0
5license: MIT
6---
7 
8## When to Use API Routes
9 
10Use API routes when you need:
11 
12- **Server-side secrets** — API keys, database credentials, or tokens that must never reach the client
13- **Database operations** — Direct database queries that shouldn't be exposed
14- **Third-party API proxies** — Hide API keys when calling external services (OpenAI, Stripe, etc.)
15- **Server-side validation** — Validate data before database writes
16- **Webhook endpoints** — Receive callbacks from services like Stripe or GitHub
17- **Rate limiting** — Control access at the server level
18- **Heavy computation** — Offload processing that would be slow on mobile
19 
20## When NOT to Use API Routes
21 
22Avoid API routes when:
23 
24- **Data is already public** — Use direct fetch to public APIs instead
25- **No secrets required** — Static data or client-safe operations
26- **Real-time updates needed** — Use WebSockets or services like Supabase Realtime
27- **Simple CRUD** — Consider Firebase, Supabase, or Convex for managed backends
28- **File uploads** — Use direct-to-storage uploads (S3 presigned URLs, Cloudflare R2)
29- **Authentication only** — Use Clerk, Auth0, or Firebase Auth instead
30 
31## File Structure
32 
33API routes live in the `app` directory with `+api.ts` suffix:
34 
35```
36app/
37  api/
38    hello+api.ts          → GET /api/hello
39    users+api.ts          → /api/users
40    users/[id]+api.ts     → /api/users/:id
41  (tabs)/
42    index.tsx
43```
44 
45## Basic API Route
46 
47```ts
48// app/api/hello+api.ts
49export function GET(request: Request) {
50  return Response.json({ message: "Hello from Expo!" });
51}
52```
53 
54## HTTP Methods
55 
56Export named functions for each HTTP method:
57 
58```ts
59// app/api/items+api.ts
60export function GET(request: Request) {
61  return Response.json({ items: [] });
62}
63 
64export async function POST(request: Request) {
65  const body = await request.json();
66  return Response.json({ created: body }, { status: 201 });
67}
68 
69export async function PUT(request: Request) {
70  const body = await request.json();
71  return Response.json({ updated: body });
72}
73 
74export async function DELETE(request: Request) {
75  return new Response(null, { status: 204 });
76}
77```
78 
79## Dynamic Routes
80 
81```ts
82// app/api/users/[id]+api.ts
83export function GET(request: Request, { id }: { id: string }) {
84  return Response.json({ userId: id });
85}
86```
87 
88## Request Handling
89 
90### Query Parameters
91 
92```ts
93export function GET(request: Request) {
94  const url = new URL(request.url);
95  const page = url.searchParams.get("page") ?? "1";
96  const limit = url.searchParams.get("limit") ?? "10";
97 
98  return Response.json({ page, limit });
99}
100```
101 
102### Headers
103 
104```ts
105export function GET(request: Request) {
106  const auth = request.headers.get("Authorization");
107 
108  if (!auth) {
109    return Response.json({ error: "Unauthorized" }, { status: 401 });
110  }
111 
112  return Response.json({ authenticated: true });
113}
114```
115 
116### JSON Body
117 
118```ts
119export async function POST(request: Request) {
120  const { email, password } = await request.json();
121 
122  if (!email || !password) {
123    return Response.json({ error: "Missing fields" }, { status: 400 });
124  }
125 
126  return Response.json({ success: true });
127}
128```
129 
130## Environment Variables
131 
132Use `process.env` for server-side secrets:
133 
134```ts
135// app/api/ai+api.ts
136export async function POST(request: Request) {
137  const { prompt } = await request.json();
138 
139  const response = await fetch("https://api.openai.com/v1/chat/completions", {
140    method: "POST",
141    headers: {
142      "Content-Type": "application/json",
143      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
144    },
145    body: JSON.stringify({
146      model: "gpt-4",
147      messages: [{ role: "user", content: prompt }],
148    }),
149  });
150 
151  const data = await response.json();
152  return Response.json(data);
153}
154```
155 
156Set environment variables:
157 
158- **Local**: Create `.env` file (never commit)
159- **EAS Hosting**: Use `eas env:create` or Expo dashboard
160 
161## CORS Headers
162 
163Add CORS for web clients:
164 
165```ts
166const corsHeaders = {
167  "Access-Control-Allow-Origin": "*",
168  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
169  "Access-Control-Allow-Headers": "Content-Type, Authorization",
170};
171 
172export function OPTIONS() {
173  return new Response(null, { headers: corsHeaders });
174}
175 
176export function GET() {
177  return Response.json({ data: "value" }, { headers: corsHeaders });
178}
179```
180 
181## Error Handling
182 
183```ts
184export async function POST(request: Request) {
185  try {
186    const body = await request.json();
187    // Process...
188    return Response.json({ success: true });
189  } catch (error) {
190    console.error("API error:", error);
191    return Response.json({ error: "Internal server error" }, { status: 500 });
192  }
193}
194```
195 
196## Testing Locally
197 
198Start the development server with API routes:
199 
200```bash
201npx expo serve
202```
203 
204This starts a local server at `http://localhost:8081` with full API route support.
205 
206Test with curl:
207 
208```bash
209curl http://localhost:8081/api/hello
210curl -X POST http://localhost:8081/api/users -H "Content-Type: application/json" -d '{"name":"Test"}'
211```
212 
213## Deployment to EAS Hosting
214 
215### Prerequisites
216 
217```bash
218npm install -g eas-cli
219eas login
220```
221 
222### Deploy
223 
224```bash
225eas deploy
226```
227 
228This builds and deploys your API routes to EAS Hosting (Cloudflare Workers).
229 
230### Environment Variables for Production
231 
232```bash
233# Create a secret
234eas env:create --name OPENAI_API_KEY --value sk-xxx --environment production
235 
236# Or use the Expo dashboard
237```
238 
239### Custom Domain
240 
241Configure in `eas.json` or Expo dashboard.
242 
243## EAS Hosting Runtime (Cloudflare Workers)
244 
245API routes run on Cloudflare Workers. Key limitations:
246 
247### Missing/Limited APIs
248 
249- **No Node.js filesystem** — `fs` module unavailable
250- **No native Node modules** — Use Web APIs or polyfills
251- **Limited execution time** — 30 second timeout for CPU-intensive tasks
252- **No persistent connections** — WebSockets require Durable Objects
253- **fetch is available** — Use standard fetch for HTTP requests
254 
255### Use Web APIs Instead
256 
257```ts
258// Use Web Crypto instead of Node crypto
259const hash = await crypto.subtle.digest(
260  "SHA-256",
261  new TextEncoder().encode("data")
262);
263 
264// Use fetch instead of node-fetch
265const response = await fetch("https://api.example.com");
266 
267// Use Response/Request (already available)
268return new Response(JSON.stringify(data), {
269  headers: { "Content-Type": "application/json" },
270});
271```
272 
273### Database Options
274 
275Since filesystem is unavailable, use cloud databases:
276 
277- **Cloudflare D1** — SQLite at the edge
278- **Turso** — Distributed SQLite
279- **PlanetScale** — Serverless MySQL
280- **Supabase** — Postgres with REST API
281- **Neon** — Serverless Postgres
282 
283Example with Turso:
284 
285```ts
286// app/api/users+api.ts
287import { createClient } from "@libsql/client/web";
288 
289const db = createClient({
290  url: process.env.TURSO_URL!,
291  authToken: process.env.TURSO_AUTH_TOKEN!,
292});
293 
294export async function GET() {
295  const result = await db.execute("SELECT * FROM users");
296  return Response.json(result.rows);
297}
298```
299 
300## Calling API Routes from Client
301 
302```ts
303// From React Native components
304const response = await fetch("/api/hello");
305const data = await response.json();
306 
307// With body
308const response = await fetch("/api/users", {
309  method: "POST",
310  headers: { "Content-Type": "application/json" },
311  body: JSON.stringify({ name: "John" }),
312});
313```
314 
315## Common Patterns
316 
317### Authentication Middleware
318 
319```ts
320// utils/auth.ts
321export async function requireAuth(request: Request) {
322  const token = request.headers.get("Authorization")?.replace("Bearer ", "");
323 
324  if (!token) {
325    throw new Response(JSON.stringify({ error: "Unauthorized" }), {
326      status: 401,
327      headers: { "Content-Type": "application/json" },
328    });
329  }
330 
331  // Verify token...
332  return { userId: "123" };
333}
334 
335// app/api/protected+api.ts
336import { requireAuth } from "../../utils/auth";
337 
338export async function GET(request: Request) {
339  const { userId } = await requireAuth(request);
340  return Response.json({ userId });
341}
342```
343 
344### Proxy External API
345 
346```ts
347// app/api/weather+api.ts
348export async function GET(request: Request) {
349  const url = new URL(request.url);
350  const city = url.searchParams.get("city");
351 
352  const response = await fetch(
353    `https://api.weather.com/v1/current?city=${city}&key=${process.env.WEATHER_API_KEY}`
354  );
355 
356  return Response.json(await response.json());
357}
358```
359 
360## Rules
361 
362- NEVER expose API keys or secrets in client code
363- ALWAYS validate and sanitize user input
364- Use proper HTTP status codes (200, 201, 400, 401, 404, 500)
365- Handle errors gracefully with try/catch
366- Keep API routes focused — one responsibility per endpoint
367- Use TypeScript for type safety
368- Log errors server-side for debugging
369