@wooksjs/fastify-adapter

Use Wooks composables with Fastify. This adapter lets you register Wooks-style route handlers on top of an existing Fastify app — unmatched requests automatically fall through to Fastify's not-found handler.

Install

npm install @wooksjs/fastify-adapter @wooksjs/event-http wooks fastify

Quick Start

import Fastify from 'fastify'
import { WooksFastify } from '@wooksjs/fastify-adapter'
import { useRouteParams, useRequest, HttpError } from '@wooksjs/event-http'

const app = Fastify()
const wooks = new WooksFastify(app)

// Return values become the response body
wooks.get('/hello/:name', () => {
    const { get } = useRouteParams()
    return { hello: get('name') }
})

// Async handlers work out of the box
wooks.post('/upload', async () => {
    const { rawBody } = useRequest()
    const body = await rawBody()
    return { received: body.length }
})

// Throw HttpError for error responses
wooks.get('/protected', () => {
    throw new HttpError(403, 'Forbidden')
})

app.listen({ port: 3000 }, () => console.log('listening on 3000'))

How It Works

WooksFastify extends WooksHttp and registers a catch-all route in Fastify. When a request comes in:

1. Wooks checks if a matching route is registered
2. If matched — the Wooks handler runs with full composable support
3. If not matched — the request falls through to Fastify's not-found handler

This means you can use Wooks composables for your route handlers while still leveraging Fastify's plugin ecosystem:

import Fastify from 'fastify'
import { WooksFastify } from '@wooksjs/fastify-adapter'

const app = Fastify()

// Wooks handles these routes
const wooks = new WooksFastify(app)
wooks.get('/api/users', () => {
    return [{ id: 1, name: 'Alice' }]
})

app.listen({ port: 3000 })

API

new WooksFastify(fastifyApp, options?)

Creates a new adapter instance and registers a catch-all route on the Fastify app.

| Option | Type | Default | Description | | ---------------- | -------------------------- | ------- | --------------------------------------------------------------------------------- | | raise404 | boolean | false | Return 404 from Wooks for unmatched routes instead of using Fastify's not-found | | onNotFound | () => unknown | — | Custom handler for unmatched routes | | logger | TConsoleBase | — | Custom logger instance | | router | object | — | Router options (ignoreTrailingSlash, ignoreCase, cacheLimit) | | requestLimits | object | — | Default request body size limits | | defaultHeaders | Record<string, string> | — | Headers added to every response | | responseClass | typeof WooksHttpResponse | — | Custom response class |

Route Methods

wooks.get(path, handler)
wooks.post(path, handler)
wooks.put(path, handler)
wooks.patch(path, handler)
wooks.delete(path, handler)
wooks.head(path, handler)
wooks.options(path, handler)
wooks.all(path, handler)

Handlers take no arguments — use composables to access request data:

wooks.get('/users/:id', () => {
    const { get } = useRouteParams()
    const { method, url, rawBody, getIp } = useRequest()
    const headers = useHeaders()
    const response = useResponse()

    response.setHeader('x-custom', 'value')
    return { id: get('id') }
})

wooks.listen(...args)

Starts the Fastify server and returns a promise that resolves when listening.

await wooks.listen({ port: 3000 })

wooks.close()

Stops the server.

await wooks.close()

Available Composables

These come from @wooksjs/event-http and work inside any Wooks handler:

| Composable | Purpose | | -------------------- | ------------------------------------------- | | useRequest() | Request method, URL, headers, body, IP | | useRouteParams() | Route parameters (:id, etc.) | | useHeaders() | Request headers | | useResponse() | Set status, headers, cookies, cache control | | useCookies() | Read request cookies | | useUrlParams() | URL query parameters | | useAuthorization() | Parse Authorization header | | useAccept() | Check Accept header | | useLogger() | Event-scoped logger |

See the Wooks documentation for full composable reference.

Development

npm install       # install dependencies
npm test          # run tests (vitest)
npm run build     # build for distribution
npm run lint      # lint with oxlint
npm run fmt       # format with oxfmt

License

MIT