1# Route Handlers
2 
3Create API endpoints with `route.ts` files.
4 
5## Basic Usage
6 
7```tsx
8// app/api/users/route.ts
9export async function GET() {
10  const users = await getUsers()
11  return Response.json(users)
12}
13 
14export async function POST(request: Request) {
15  const body = await request.json()
16  const user = await createUser(body)
17  return Response.json(user, { status: 201 })
18}
19```
20 
21## Supported Methods
22 
23`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
24 
25## GET Handler Conflicts with page.tsx
26 
27**A `route.ts` and `page.tsx` cannot coexist in the same folder.**
28 
29```
30app/
31├── api/
32│   └── users/
33│       └── route.ts    # /api/users
34└── users/
35    ├── page.tsx        # /users (page)
36    └── route.ts        # Warning: Conflicts with page.tsx!
37```
38 
39If you need both a page and an API at the same path, use different paths:
40 
41```
42app/
43├── users/
44│   └── page.tsx        # /users (page)
45└── api/
46    └── users/
47        └── route.ts    # /api/users (API)
48```
49 
50## Environment Behavior
51 
52Route handlers run in a **Server Component-like environment**:
53 
54- Yes: Can use `async/await`
55- Yes: Can access `cookies()`, `headers()`
56- Yes: Can use Node.js APIs
57- No: Cannot use React hooks
58- No: Cannot use React DOM APIs
59- No: Cannot use browser APIs
60 
61```tsx
62// Bad: This won't work - no React DOM in route handlers
63import { renderToString } from 'react-dom/server'
64 
65export async function GET() {
66  const html = renderToString(<Component />)  // Error!
67  return new Response(html)
68}
69```
70 
71## Dynamic Route Handlers
72 
73```tsx
74// app/api/users/[id]/route.ts
75export async function GET(
76  request: Request,
77  { params }: { params: Promise<{ id: string }> }
78) {
79  const { id } = await params
80  const user = await getUser(id)
81 
82  if (!user) {
83    return Response.json({ error: 'Not found' }, { status: 404 })
84  }
85 
86  return Response.json(user)
87}
88```
89 
90## Request Helpers
91 
92```tsx
93export async function GET(request: Request) {
94  // URL and search params
95  const { searchParams } = new URL(request.url)
96  const query = searchParams.get('q')
97 
98  // Headers
99  const authHeader = request.headers.get('authorization')
100 
101  // Cookies (Next.js helper)
102  const cookieStore = await cookies()
103  const token = cookieStore.get('token')
104 
105  return Response.json({ query, token })
106}
107```
108 
109## Response Helpers
110 
111```tsx
112// JSON response
113return Response.json({ data })
114 
115// With status
116return Response.json({ error: 'Not found' }, { status: 404 })
117 
118// With headers
119return Response.json(data, {
120  headers: {
121    'Cache-Control': 'max-age=3600',
122  },
123})
124 
125// Redirect
126return Response.redirect(new URL('/login', request.url))
127 
128// Stream
129return new Response(stream, {
130  headers: { 'Content-Type': 'text/event-stream' },
131})
132```
133 
134## When to Use Route Handlers vs Server Actions
135 
136| Use Case | Route Handlers | Server Actions |
137|----------|----------------|----------------|
138| Form submissions | No | Yes |
139| Data mutations from UI | No | Yes |
140| Third-party webhooks | Yes | No |
141| External API consumption | Yes | No |
142| Public REST API | Yes | No |
143| File uploads | Both work | Both work |
144 
145**Prefer Server Actions** for mutations triggered from your UI.
146**Use Route Handlers** for external integrations and public APIs.
147