Mount Better Auth without an adapter
Hono or Cloudflare Workers
Better Auth · Module
auth.handler
auth.handler is Better Auth's Web Standard request handler. Mount it on a catch-all route matching the configured auth base path and pass the incoming Request to receive a Response.
How it works
The handler is the request entry point for Better Auth. Mount it on a catch-all route matching the configured base path, pass the incoming Web Standard Request to it, and return the resulting Response.
Syntax
auth.handler(request)Parameters
| Name | Type | Description |
|---|---|---|
request | Request | Incoming Web Standard HTTP request containing the method, URL, headers, and optional body. |
Returns
A Web Standard Response generated by Better Auth.
Key points
- The handler can work directly with frameworks that expose Web Standard Request and Response objects.
- A Hono catch-all route can forward authentication traffic by passing
c.req.rawto the handler. - The handler validates the incoming HTTP method and produces the response that the framework returns.
- When Hono already applies an
/apibase path, define the auth route as/auth/*within that application.
Common mistakes
- The route pattern must correspond to Better Auth's configured basePath; the default is
/api/auth. - Place the authentication route before broader catch-all routes so another handler does not intercept requests.
- In Hono, forward the raw Web Standard Request rather than the framework wrapper.
Example: Mount the Better Auth handler
import { auth } from "./auth";
export async function GET(request: Request) {
return auth.handler(request);
}
export async function POST(request: Request) {
return auth.handler(request);
}Forward GET and POST Web Standard requests to Better Auth from a catch-all authentication route.
When to use it
Expose authentication endpoints
Framework catch-all API route
Route requests under a configured auth prefix
Custom base path deployment
Interview questions
QWhat is the role of auth.handler?
auth.handler is the server-side request handler exposed by a Better Auth instance. A framework route passes it a Web Standard Request, and the returned Response is sent back to the client.
Follow-up: How would you mount it in Hono? Use app.all on the matching auth path and call auth.handler(c.req.raw).
QHow should the handler be exposed by a framework route?
Mount the handler on a catch-all authentication route and export it for the HTTP methods your framework supports. The route should match the configured Better Auth base path, which defaults to /api/auth.
Follow-up: What happens if the route does not match the base path? Requests may not reach Better Auth, so the configured route pattern and basePath must be aligned.
QWhy can Hono mount auth.handler directly?
Hono and Better Auth both use the Web Standard Request and Response APIs, so Hono can call the handler directly without an adapter. The raw request is supplied through c.req.raw.
Follow-up: Why is a raw request needed? It preserves the Web Standard request object expected by Better Auth instead of passing Hono's context wrapper.
Related
basePathRequestResponseHonoc.req.raw