A route.ts file and a page.tsx file can never occupy the same route segment, a segment either renders UI or responds like an API endpoint, never both. Choosing between a Route Handler and a Server Action for a given mutation comes down to one question: does anything other than your own app's UI need to call this?
route-handlersapi-routesroute-tsweb-standard-apis
Curated Video Reference
YouTube
Hand-picked video lecture to deepen your understanding of Route Handlers / API Routes
1. What HTTP methods can a route.ts file export handlers for?
Interview Questions
2 questions
Cheatsheet
Download-ready reference
Cheatsheet
route.ts exports async functions named after HTTP methods:
GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
Uses standard Request/Response (NextRequest extends Request).
OPTIONS auto-implemented if not defined (correct Allow header).
context.params is a PROMISE, same contract as page/layout params.
RouteContext<'/route'> = auto-generated typed helper.
A route segment = page.tsx OR route.ts, NEVER both (structural
conflict, not a config choice).
Route Handler vs Server Action:
Route Handler → external callers (public API, webhooks, mobile
apps), full response-format control
Server Action → mutations tied to YOUR OWN UI's forms, single
round-trip (mutation + fresh UI), progressive
enhancement built in
GET Route Handlers under Cache Components: SAME prerendering model
as pages. generateStaticParams works with dynamic Route Handlers
too, prerenders specific API responses at build time.
The beginner framing: a route.ts file lets you build a custom request handler for a specific path, the App Router's equivalent of a traditional API endpoint, using standard Request and Response objects instead of rendering a React component.
The precise mental model: a route.ts file exports one async function per HTTP method it supports (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS), each receiving a NextRequest (an extension of the standard Request) and returning a Response.
// app/api/users/route.tsexport async function GET(request: NextRequest) { const url = request.nextUrl; // a parsed URL object, a NextRequest convenience return Response.json({ message: "Hello World" });}export async function POST(request: Request) { const body = await request.json(); const user = await db.user.create({ data: body }); return Response.json(user, { status: 201 });}
If OPTIONS isn't defined, Next.js automatically implements it, setting the appropriate Allow header based on whichever other methods you've defined.
context.params, the same Promise-based contract as pages#
// app/dashboard/[team]/route.tsexport async function GET( request: Request, { params }: { params: Promise<{ team: string }> }) { const { team } = await params; // ⚠️ same Promise contract as page/layout params return Response.json({ team });}
RouteContext<'/route'> is the auto-generated helper type for this, exactly like PageProps/LayoutProps are for pages and layouts.
A route segment is EITHER a page or a Route Handler, never both#
A single route segment can have a page.tsx (rendering UI) or a route.ts (a custom handler), not both at once, since they'd both be trying to respond to the exact same path.
Route Handlers vs. Server Actions: picking the right tool#
Route Handler
Server Action
Best for
A public API, webhooks, anything called by clients OUTSIDE your own React tree
Mutations tied to your own app's forms/UI
Response format
You control it fully, any content type, custom headers/status
Automatically returns fresh UI + result together
Called from
Any HTTP client, curl, a webhook provider, a mobile app
Your own <form>/event handlers (though also reachable via direct POST, see Server Actions)
If the only thing that will ever call this endpoint is your own app's own form, a Server Action is usually the simpler, more direct tool, a Route Handler earns its keep specifically when something outside your React tree needs to talk to it, or when you need response-format control a Server Action's contract doesn't offer.
Under Cache Components, GET Route Handlers follow the same prerendering model as pages, a GET handler with no runtime API access can be prerendered at build time, and "use cache" applies to it exactly as it would to a page (see Caching). generateStaticParams also works with dynamic Route Handlers, prerendering specific API responses at build time for known parameter values.
Predict what happens before checking the solution.
// app/api/widgets/route.tsexport async function GET() { return Response.json({ widgets: [] }); }export async function POST() { return Response.json({ created: true }); }// no OPTIONS defined
A client sends an OPTIONS request to /api/widgets. What happens?
Solution
Next.js automatically implements OPTIONS for you, responding with the correct Allow header listing the methods actually defined, in this case, GET, POST (plus HEAD, which is automatically derivable from GET). No manual OPTIONS export is needed unless you want custom behavior beyond the automatic default.
This mirrors the real mechanism: each exported function name IS the dispatch key, and a missing OPTIONS gets a sensible, automatic default built from whatever methods you did define.
NextRequest/Response being extensions of the standard Fetch API's Request/Response objects means a Route Handler is, at its core, working with the exact same web-standard interfaces used throughout the rest of the web platform, nothing Next.js-specific about the shape of the request/response themselves. And a GET Route Handler's ability to be prerendered under Cache Components is the identical Caching model applied to a different kind of route segment, the "static shell vs. runtime data" distinction doesn't care whether the segment renders a page or returns JSON.
1. Trying to have both page.tsx and route.ts in the same segment#
app/products/ page.tsx // ❌ conflicts, pick ONE route.ts
A route segment serves either UI or a custom request handler, never both at the same path, this is a structural conflict, not a configuration option to resolve.
2. Reaching for a Route Handler when a Server Action would be simpler#
If the only caller is your own app's own form, a Route Handler adds an extra network round-trip contract (you'd typically fetch it from a Client Component) that a Server Action already handles more directly, in one round-trip, with automatic progressive enhancement built in.
3. Forgetting params is a Promise in Route Handlers too#
Exactly the same mistake covered in Dynamic Routes, context.params must be awaited here as well, not accessed synchronously.
Reach for Route Handlers when something outside your own React tree needs to call this endpoint, a public API, a webhook receiver, a mobile client.
Reach for Server Actions for mutations tied to your own app's UI, getting the single-round-trip and progressive-enhancement benefits for free.
Let GET handlers with no runtime dependencies be prerendered/cached under Cache Components, exactly like a page, don't assume every API route must be fully dynamic.
Use RouteContext<'/route'> to correctly type params for a specific route, rather than hand-writing the shape.
A cacheable GET Route Handler (no runtime API access) gets the same prerendering benefits as a static page, real, measurable latency savings for API responses that don't need to be computed fresh on every request.
generateStaticParams applies to dynamic Route Handlers just as it does to pages, prerendering known API responses at build time avoids recomputing them for every request to a well-known set of resources.