Custom Integration

Don't see your framework listed? The evlog/toolkit package exposes the same building blocks that power every built-in integration (Hono, Express, Fastify, Elysia, NestJS, SvelteKit). Build a full-featured evlog middleware for any HTTP framework in ~30 lines of code.

Install

pnpm add evlog

bun add evlog

yarn add evlog

npm install evlog

What's in the Toolkit

Types like RequestLogger, DrainContext, EnrichContext, WideEvent, and TailSamplingContext are exported from the main evlog package.

Manifest Mode (recommended)

Most frameworks fit a (ctx, next) middleware shape. For those, write a manifest describing how to extract the request and attach the logger — defineFrameworkIntegration does the rest.

import type { IncomingMessage, ServerResponse } from 'node:http'
import {
  createLoggerStorage,
  defineFrameworkIntegration,
  type BaseEvlogOptions,
} from 'evlog/toolkit'
import type { RequestLogger } from 'evlog'

export type MyFrameworkEvlogOptions = BaseEvlogOptions

const { storage, useLogger } = createLoggerStorage(
  'middleware context. Make sure evlog middleware is registered before your routes.',
)

export { useLogger }

const integration = defineFrameworkIntegration<IncomingMessage>({
  name: 'my-framework',
  extractRequest: (req) => ({
    method: req.method || 'GET',
    path: req.url || '/',
    headers: req.headers,
    requestId: typeof req.headers['x-request-id'] === 'string'
      ? req.headers['x-request-id']
      : undefined,
  }),
  attachLogger: (req, logger) => {
    (req as IncomingMessage & { log: RequestLogger }).log = logger
  },
  storage,
})

export function evlog(options: MyFrameworkEvlogOptions = {}) {
  return async (req: IncomingMessage, res: ServerResponse, next: () => Promise<void>) => {
    const { skipped, finish, runWith } = integration.start(req, options)
    if (skipped) {
      await next()
      return
    }
    try {
      await runWith(() => next())
      await finish({ status: res.statusCode })
    } catch (error) {
      await finish({ error: error as Error })
      throw error
    }
  }
}

That's it. This middleware gets every feature for free: route filtering, drain adapters, enrichers, tail sampling, error capture, plugin lifecycle hooks, log.fork(), and duration tracking.

What defineFrameworkIntegration does

Given the manifest above, the helper:

1. Normalizes headers (auto-detects Headers vs IncomingHttpHeaders).
2. Generates a requestId if extractRequest doesn't return one.
3. Calls createMiddlewareLogger with the merged options.
4. Calls attachLogger(ctx, logger).
5. Attaches log.fork() to the logger when storage is provided (so users can spawn correlated background work).
6. Exposes runWith(fn) — runs fn() inside storage.run(logger, …) if storage is configured, otherwise just calls fn().

You're left with only the framework-specific glue: where to read the request from, where to attach the logger, and how to compute the response status.

Custom Mode

If your framework's lifecycle doesn't fit a clean (ctx, next) shape (NestJS interceptors, Next.js App Router, SvelteKit handle), drop one level lower and call createMiddlewareLogger directly:

import { createMiddlewareLogger, extractSafeNodeHeaders } from 'evlog/toolkit'

const { logger, finish, skipped } = createMiddlewareLogger({
  method,
  path,
  requestId,
  headers: extractSafeNodeHeaders(rawHeaders),
  ...options,
})

You'll be responsible for ALS wrapping (storage.run), log.fork() attachment (via attachForkToLogger), and finishing the lifecycle — but you keep the full pipeline (route filtering, sampling, emit, enrich, drain, plugins) for free.

Reference Implementations

Study these built-in integrations for framework-specific patterns:

Next Steps

• Toolkit reference: All toolkit primitives in one place
• Wide Events: Design comprehensive events with context layering
• Adapters: Send logs to Axiom, Sentry, PostHog, and more
• Sampling: Control log volume with head and tail sampling
• Structured Errors: Throw errors with why, fix, and link fields