---
title: Raw handlers
description: Mount native Request-to-Response adapters with ALL and understand what bypasses the typed function-route pipeline.
pagination: false
sidebar:
  icon: code-xml
---

Mount a raw route when an integration already provides a native `Request`-to-`Response` handler. Use a [function-backed route](/docs/modules/http/define) for ordinary domain
operations that need RELKIT input validation, declared errors, and generated contracts.

> **Create the route from the terminal**
>
> Use [`relkit add route --mode route`](/docs/modules/http/define#scaffold-a-route) to create a raw
> `GET` handler, then replace its placeholder with your integration. For Better Auth, use [`relkit
> add auth`](/docs/modules/auth/better-auth#scaffold-the-auth-baseline), which creates the
> specialized service and its `ALL` mount together.

## Mount an HTTP integration

A raw route uses `defineRoute({ handler: ... })` and the named export `ALL`:

The auth example below requires complete [Better Auth installation and configuration](/docs/modules/auth/better-auth)
first. A minimal app does not acquire the auth SDK or database by copying this route.

```ts title="examples/commerce/src/routes/api/auth/[[...auth]]/route.ts"
/** Mounts the native Better Auth handler once for all methods and protects account/MCP application paths. */
import { defineRoute } from "@relkit/app/routes";
import auth from "../../../../services/auth/service.js";

export const ALL = defineRoute({
  // Forward every Better Auth method through one filesystem route.
  // Only the listed application paths require an authenticated session.
  handler: auth.handler,
  auth: { protected: ["/account/*", "/mcp"] },
});
```

This optional catch-all mounts the auth adapter at `/api/auth` and its nested paths. `ALL` delegates
every HTTP method at those paths; the adapter decides which operations it accepts.
The handler accepts a native `Request` and returns a `Response`, synchronously or asynchronously.

Do not combine `handler` and `target`, export a raw handler as `GET` or `POST`, or pass `ALL` to
`defineServiceRoutes`. Route file naming and collision checks still apply.

## Understand the boundary

| Behavior                                              | Function-backed route                              | Raw route                               |
| ----------------------------------------------------- | -------------------------------------------------- | --------------------------------------- |
| Entry point                                           | Public service function                            | Native HTTP handler                     |
| Input parsing and validation                          | Inferred or explicit mapping, then function schema | Owned by the adapter                    |
| Response construction                                 | Function output and declared response contract     | Adapter returns the complete `Response` |
| Function invocation context and declared dependencies | Available inside the target                        | No automatic function invocation        |
| Route `rateLimit`, `request`, and `responses` options | Supported                                          | Not part of the raw-handler API         |
| OpenAPI and generated-client operation                | Generated                                          | Excluded                                |

Framework request setup and matching HTTP middleware still surround raw routes. Do not assume this
makes arbitrary adapter body reads bounded or validates their payloads: configure the adapter's own
limits, signature checks, session security, and error handling. Use middleware or an upstream gateway
for transport policy that the raw-route API does not provide.

## Keep Better Auth protection explicit

The example's `auth.protected` list protects `/account/*` and `/mcp` using the registered Better Auth
service. It is not a list of routes created by the auth handler. The adapter owns the `/api/auth`
endpoints; protected paths select other application entry points that require a session.

The `auth` option is accepted only when `handler` belongs to a recognized Better Auth service.
It cannot add authentication to an arbitrary raw handler. This route also needs the corresponding
auth service and database configuration; copying only the route is not a complete auth setup.
See the [specialized service guidance](/docs/modules/service/organization#resources-do-not-go-in-the-service-member-list)
for the owning domain and the [Routes API reference](/docs/api/routes) for raw-route options.
Use [Better Auth service](/docs/modules/auth/better-auth) for a complete setup and
[Protect routes](/docs/modules/auth/protect-routes) for exact path matching and authorization boundaries.

## Verify the adapter separately

From the application root, run `bun run check`. Then test the base catch-all path, a nested path,
an unsupported method, a protected request without a session, and one with a valid session.
Assert the adapter's actual statuses, headers, and cookies; there is no generated route contract
to supply those assertions. Use the [testing guide](/docs/modules/operations/testing) for the application harness.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/routes` API](/docs/api/routes)

- [`examples/commerce/src/routes/api/auth/[[...auth]]/route.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/routes/api/auth/[[...auth]]/route.ts)