Simple API endpoints with a default-exported Request → Response function.
Plain function handlers are the simplest way to create API routes. Export a function from a file in src/app/api/ and it becomes an endpoint at /api/*. Ideal for single endpoints that do not need Hono middleware or nested routing.
src/app/api/hello.ts is served at /api/hello. There is no bare /api root route.Export a default function that receives a Request and a context object. The file path sets the route - the function name does not matter.
This creates /api/hello and responds to all HTTP methods unless you branch on request.method.
File structure maps directly to API paths:
| File Path | API Route |
|---|---|
| src/app/api/hello.ts | /api/hello |
| src/app/api/users.ts | /api/users |
| src/app/api/posts/index.ts | /api/posts |
| src/app/api/posts/[id].ts | /api/posts/:id |
| src/app/api/[...catch].ts | /api/* |
Every handler receives a second argument with the route context. Use it for path params, query parameters, and runtime env bindings.
| Field | Type | Description |
|---|---|---|
| params | object | Dynamic route params (e.g. { id: "123" }) |
| searchParams | URLSearchParams | Query string parameters |
| env | any | Runtime env bindings (or process.env on Node) |
| waitUntil? | function | Extends the request lifetime for background work |
Branch on request.method for different verbs, or export per-method handlers (GET, POST, etc.) instead of a default function.
| Method | Typical Use |
|---|---|
| GET | Retrieve data |
| POST | Create new data |
| PUT | Replace existing data |
| PATCH | Partially update data |
| DELETE | Remove data |
Instead of one default function that branches on request.method, export a separate function for each HTTP verb. Each one is a plain function that receives the same Request and context object, and returns a Response.
The context object is passed as the second argument, exactly like a default function:
| Behavior | Details |
|---|---|
| Supported exports | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
| Unhandled methods | Return 405 with an Allow header |
| HEAD fallback | Falls back to GET when no HEAD export exists |
| Precedence | Method exports take precedence over a default export |
Body, headers, and query params:
Common response patterns:
Path params are available in the context object, not a header. Use { params } as the second argument:
[...catch] handles unmatched /api/* paths. Catch-all values are available under params['*'] and under the folder name.
Access environment variables directly from the env object in the request context. This ensures your code works across all deployment platforms.
env is backed by process.env. On edge platforms, it reads the runtime bindings.Validate input and catch unexpected failures:
| Scenario | Recommendation |
|---|---|
| Single endpoint with simple logic | Plain handler |
| Quick prototypes | Plain handler |
| Simple CRUD | Plain handler |
| Method-based dispatch without branching | Plain handler (per-method exports) |
| Multiple endpoints in one file | Use Hono |
| Need middleware | Use Hono |
| Complex routing | Use Hono |
| Large production API surface | Use Hono |
Files under app/api/ map to /api/*.
Build API routes with the Hono framework.
Path parameters and catch-all segments.
Read secrets in your API routes.
Deploy to Node, Vercel, Netlify, Cloudflare, or Deno.
Fetch data before a route renders.
Simple API endpoints with a default-exported Request → Response function.
Plain function handlers are the simplest way to create API routes. Export a function from a file in src/app/api/ and it becomes an endpoint at /api/*. Ideal for single endpoints that do not need Hono middleware or nested routing.
src/app/api/hello.ts is served at /api/hello. There is no bare /api root route.Export a default function that receives a Request and a context object. The file path sets the route - the function name does not matter.
This creates /api/hello and responds to all HTTP methods unless you branch on request.method.
File structure maps directly to API paths:
| File Path | API Route |
|---|---|
| src/app/api/hello.ts | /api/hello |
| src/app/api/users.ts | /api/users |
| src/app/api/posts/index.ts | /api/posts |
| src/app/api/posts/[id].ts | /api/posts/:id |
| src/app/api/[...catch].ts | /api/* |
Every handler receives a second argument with the route context. Use it for path params, query parameters, and runtime env bindings.
| Field | Type | Description |
|---|---|---|
| params | object | Dynamic route params (e.g. { id: "123" }) |
| searchParams | URLSearchParams | Query string parameters |
| env | any | Runtime env bindings (or process.env on Node) |
| waitUntil? | function | Extends the request lifetime for background work |
Branch on request.method for different verbs, or export per-method handlers (GET, POST, etc.) instead of a default function.
| Method | Typical Use |
|---|---|
| GET | Retrieve data |
| POST | Create new data |
| PUT | Replace existing data |
| PATCH | Partially update data |
| DELETE | Remove data |
Instead of one default function that branches on request.method, export a separate function for each HTTP verb. Each one is a plain function that receives the same Request and context object, and returns a Response.
The context object is passed as the second argument, exactly like a default function:
| Behavior | Details |
|---|---|
| Supported exports | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
| Unhandled methods | Return 405 with an Allow header |
| HEAD fallback | Falls back to GET when no HEAD export exists |
| Precedence | Method exports take precedence over a default export |
Body, headers, and query params:
Common response patterns:
Path params are available in the context object, not a header. Use { params } as the second argument:
[...catch] handles unmatched /api/* paths. Catch-all values are available under params['*'] and under the folder name.
Access environment variables directly from the env object in the request context. This ensures your code works across all deployment platforms.
env is backed by process.env. On edge platforms, it reads the runtime bindings.Validate input and catch unexpected failures:
| Scenario | Recommendation |
|---|---|
| Single endpoint with simple logic | Plain handler |
| Quick prototypes | Plain handler |
| Simple CRUD | Plain handler |
| Method-based dispatch without branching | Plain handler (per-method exports) |
| Multiple endpoints in one file | Use Hono |
| Need middleware | Use Hono |
| Complex routing | Use Hono |
| Large production API surface | Use Hono |
Files under app/api/ map to /api/*.
Build API routes with the Hono framework.
Path parameters and catch-all segments.
Read secrets in your API routes.
Deploy to Node, Vercel, Netlify, Cloudflare, or Deno.
Fetch data before a route renders.