hulla.dev

Server adapters

H3

Add your API routes to an H3 v2 app.

On this page

Add your contract’s routes to an H3 v2 app with @hulla/api-h3. The routes use H3’s middleware and event context.

For Nuxt, use @hulla/api-nuxt, which supports Nuxt’s H3 v1 integration.

The adapter requires Node.js 22 or later and supports H3 ^2.0.1-rc.29. Install that H3 v2 range explicitly. This example uses Zod for request and response schemas.

Declare the HTTP boundary in a module shared by server and client code:

TypeScript
// src/api/contract.ts
import { defineContract, request, response, route } from '@hulla/api'
import { z } from 'zod'

export const contract = defineContract({
  basePath: '/api',
  routes: {
    renameUser: route.patch('/users/:id', {
      params: z.object({ id: z.string() }),
      body: request.json(z.object({ name: z.string().min(1) })),
      responses: {
        200: response.json(
          z.object({
            id: z.string(),
            name: z.string(),
            actor: z.string(),
          })
        ),
      },
    }),
  },
})

Implement the route in server-only code. The handler receives decoded, validated inputs, and response() only accepts a status and body declared by the contract:

TypeScript
// src/api/server.ts
import { defineServer } from '@hulla/api/server'
import { contract } from './contract'

export const implementation = defineServer(contract).implement({
  renameUser: ({ params, body, response }) =>
    response(200, {
      id: params.id,
      name: body.name,
      actor: 'api',
    }),
})

Create the H3 app, register host middleware, and mount the implementation:

TypeScript
// src/app.ts
import { h3Adapter } from '@hulla/api-h3'
import { H3 } from 'h3'
import { implementation } from './api/server'

export const app = new H3()

app.use(async (_event, next) => {
  const result = await next()
  if (result instanceof Response) {
    result.headers.set('x-host', 'h3')
  }
  return result
})

const adapter = h3Adapter(app)
adapter.mount(implementation)

mount() registers every selected contract route through H3’s native app.on() API and returns that same app. Verify the integration without opening a network port by using H3’s request helper:

TypeScript
// scripts/verify-api.ts
import { app } from '../src/app'

const result = await app.request('/api/users/user%201', {
  method: 'PATCH',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ name: 'Grace' }),
})

console.log(result.status) // 200
console.log(result.headers.get('x-host')) // h3
console.log(await result.json())
// { id: 'user 1', name: 'Grace', actor: 'api' }

The request enters H3’s router, runs the host middleware and contract handler, and returns a standard Web Response. In a Node.js entry point, pass the same app to H3’s server:

TypeScript
import { serve } from 'h3'
import { app } from './app'

serve(app)

Other H3 runtime adapters can consume app.fetch or the app itself. @hulla/api-h3 does not choose a deployment target or start a server.

Register H3 middleware before mount() when it must wrap a contract route. H3 uses the app’s native middleware and router order.

For a matched contract route:

  1. H3 matches the method and path, then enters middleware registered before the route.
  2. The adapter reads path parameters, the URL query, headers, and the declared body representation.
  3. @hulla/api validates those values, creates server context, runs its middleware, and calls the handler.
  4. The Web Response returns through the remaining H3 middleware.

Native H3 behavior still applies:

  • unmatched requests continue to other H3 routes and not-found handling;
  • mounting a server fragment registers only its selected routes;
  • a HEAD request can use a matching contract GET route, with H3 suppressing the body;
  • custom contract QUERY routes are registered as native H3 QUERY routes;
  • repeated query values are preserved from event.url.searchParams.

Use the contract handler’s params for decoded and validated values. H3 keeps wire-form router parameters on event.context.params: for example, user%201 becomes user 1 in the contract handler. H3’s safe decoder deliberately preserves an encoded slash as %2F. Avoid slash-containing identifiers when one contract must produce identical parameter values across different native routers.

Choose who reads the request body

A Web request body can be consumed once. Choose the setup based on which H3 layer needs it:

ReadersSetupResult
Contract route onlyUse the default mountThe adapter reads event.req in the contract’s JSON, text, bytes, or form-data representation.
H3 middleware and contract routeRead event.req.clone() in the middlewareMiddleware consumes the clone; the original remains available to the adapter.
Contract route and adapter-bound context factorySet preserveRequestBody: trueThe adapter decodes a clone; the context factory can read the original request.

Reading event.req directly in earlier middleware consumes the original stream and cannot be undone later. Clone it before the first read when another layer still needs the body.

The adapter imposes no body-size limit by default. Set maxBodyBytes to bound its read; H3, a proxy, or the deployment runtime may enforce separate limits:

TypeScript
const adapter = h3Adapter(app, { maxBodyBytes: 1_048_576 })
adapter.mount(implementation, { preserveRequestBody: true })

Adapter defaults apply to every mount. Options passed to mount() shallowly override those defaults for that implementation or fragment.

Keep the context factory portable when it only needs application services or route metadata. Use adapter.context() when handlers need H3 event context, the prepared response, runtime details, or waitUntil():

TypeScript
import { defineServer } from '@hulla/api/server'
import { h3Adapter } from '@hulla/api-h3'
import { H3 } from 'h3'
import { contract } from './api/contract'

const app = new H3()
app.use((event) => {
  event.context['actor'] = 'Ada'
})

const adapter = h3Adapter(app)
const implementation = defineServer(contract, {
  context: adapter.context(({ request, h3Event, route }) => ({
    actor: String(h3Event.context['actor']),
    requestId: request.headers.get('x-request-id'),
    routeKey: route.key.join('.'),
  })),
}).implement({
  renameUser: ({ params, body, context, response }) => {
    console.info({
      requestId: context.requestId,
      route: context.routeKey,
    })
    return response(200, {
      id: params.id,
      name: body.name,
      actor: context.actor,
    })
  },
})

adapter.mount(implementation)

The factory receives:

  • request: the Web Request exposed by h3Event.req;
  • h3Event: H3’s native event, including mutable context, parsed URL, prepared response, runtime details, and waitUntil();
  • route: the contract route key, HTTP method, and full path.

adapter.context() binds the implementation to the H3 adapter. Mounting it through Fetch, another framework adapter, or the in-process transport fails immediately. Context code should return values for the server handler rather than finalizing a separate H3 response.

Use onError for failures while the adapter decodes contract inputs, creates context, runs @hulla/api middleware or the handler, serializes the declared result, or converts it to a Web Response:

TypeScript
const adapter = h3Adapter(app, {
  onError({ error, phase, request, h3Event, defaultResponse }) {
    console.error(phase, request.url, h3Event.url.pathname, error)
    return defaultResponse
  },
})

The hook receives the H3 event and a protocol-safe default Response. Return another Response to replace it, or return undefined to keep the default. Options passed to mount() override adapter defaults for that mount; onError: undefined disables an inherited hook.

H3’s error pipeline owns failures from H3 middleware and native routes outside the mounted adapter. If a stream producer fails after its response has started, onError can observe the transport failure but cannot replace the response already in flight.

Declared stream bodies must be iterable or async iterable and yield Uint8Array chunks. The adapter exposes the source as a Web ReadableStream without collecting the complete body first. Finishing, cancelling, or failing the stream closes its source iterator.

The native request’s AbortSignal becomes the handler’s signal. When the H3 runtime aborts that request signal, the handler can use it to stop database, file, or network work.