Custom Framework Integration

When the framework you use doesn't have an evlog/<framework> package yet, you build the integration yourself. evlog/toolkit ships the same building blocks that power every built-in integration (Hono, Express, Fastify, Elysia, NestJS, SvelteKit) — you only write the framework-specific glue.

The mental model is always the same: request lifecycle → logger creation → enrich → drain. The toolkit handles the request-context plumbing.

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(
  'Cannot access logger outside of 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.

Non-HTTP runtimes

For queue workers, CLI drivers, cron jobs, or durable execution engines, skip the HTTP-shaped helpers and use createRequestLogger from evlog/toolkit directly:

import { createRequestLogger } from 'evlog/toolkit'

async function processJob(job: Job) {
  const logger = createRequestLogger({
    service: 'jobs',
    context: { jobId: job.id, queue: job.queue },
  })

  try {
    await runJob(job)
    logger.set({ status: 'success' })
  } catch (err) {
    logger.error(err)
    throw err
  } finally {
    await logger.emit()
  }
}

Same enrichers, same drain hook, same identity headers on outbound HTTP drain requests — only the entry point shape changes.

Reference implementations

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

Next steps

• Custom Drains — same toolkit shape for drain destinations
• Custom Enrichers — same toolkit shape for derived event fields
• Plugins — multi-hook extensions (drain + enrich + keep in one object)
• Wide Events — design comprehensive events with context layering
• Sampling — control log volume with head and tail sampling
• Adapters — send logs to Axiom, Sentry, PostHog, and more