evlog Framework Integration

Create evlog Framework Integration

Add a new framework integration to evlog. The recommended path is the manifest mode built on defineFrameworkIntegration from evlog/toolkit, for any framework with a request/response middleware shape. For frameworks with a fundamentally different lifecycle you'll fall back to the lower-level createMiddlewareLogger.

Two paths

• Manifest mode (preferred, ~30–80 lines of glue). Call defineFrameworkIntegration({ name, extractRequest, attachLogger, storage? }) once at module level, then write a tiny middleware that calls integration.start(ctx, options) and runs the framework's next() inside runWith. Reference implementations: all of packages/evlog/src/{hono,express,fastify,elysia,nestjs,orpc,react-router,sveltekit,workers}/index.ts use it.
• Custom mode: use createMiddlewareLogger directly when the framework's lifecycle doesn't fit a standard middleware. Current custom-mode integrations: Next.js (src/next/), Nitro v2/v3 (src/nitro/, src/nitro-v3/), Eve (src/eve/).

Manifest mode now covers all classic HTTP frameworks. Use custom mode only when you can't extract a request synchronously at the start of the lifecycle (server actions, module-level hooks, agent turns).

Required API surface (from AGENTS.md)

Every framework integration must expose:

1. evlog() middleware/plugin accepting the full BaseEvlogOptions (drain, enrich, keep, include, exclude, routes, plugins)
2. useLogger() (ALS-backed). Workers is the one sanctioned exception (ALS needs a compat flag there; defineWorkerFetch attaches the logger instead)
3. log.fork() support (automatic when storage is provided to the manifest)
4. The framework-native accessor (c.get('log'), req.log, event.locals.log, …)

PR Title

feat({framework}): add {Framework} middleware integration

Scope timing caveat: the semantic PR check reads its scope list from the base branch, so a brand-new scope can't validate the very PR that introduces it. Either register the scope in a small preceding PR, or use an unscoped title (feat: add {Framework} middleware integration) on the introducing PR.

Touchpoints Checklist

Important: Do NOT consider the task complete until all 15 touchpoints have been addressed.

Naming Conventions

Shared Utilities

All integrations share the same core utilities. Never reimplement logic that exists in shared/. These are also publicly available as evlog/toolkit for community-built integrations (see Custom Integration docs).

defineFrameworkIntegration automatically:

• normalizes both Web Headers and Node IncomingHttpHeaders (so you don't need to pick a header extractor)
• generates a requestId when none is present
• calls createMiddlewareLogger and surfaces its { logger, finish, skipped, middlewareOptions }
• attaches log.fork() automatically when storage is provided
• exposes runWith(fn) to run downstream handlers inside the integration's ALS
• forwards waitUntil when the runtime provides one (Workers, Hono on Workers)

Step 1: Integration Source

Create packages/evlog/src/{framework}/index.ts.

Template Structure (manifest mode)

import type { AuditableLogger } from '../audit'
import { defineFrameworkIntegration } from '../shared/integration'
import type { BaseEvlogOptions } from '../shared/middleware'
import { createLoggerStorage } from '../shared/storage'

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

export type Evlog{Framework}Options = BaseEvlogOptions
export { useLogger }

// Type augmentation for typed logger access (framework-specific):
// - Express: declare module 'express-serve-static-core' { interface Request { log: AuditableLogger } }
// - Hono:    export type EvlogVariables = { Variables: { log: AuditableLogger } }

const integration = defineFrameworkIntegration<{Framework}Context>({
  name: '{framework}',
  extractRequest: (ctx) => ({
    method: /* ctx.method */,
    path: /* ctx.path */,
    headers: /* Web Headers OR Node headers OR plain object */,
    requestId: /* x-request-id header or undefined → auto-generated */,
  }),
  attachLogger: (ctx, logger) => {
    // Store in framework-idiomatic location:
    // - Hono:    c.set('log', logger)
    // - Express: req.log = logger
  },
  storage,
})

export function evlog(options: Evlog{Framework}Options = {}): FrameworkMiddleware {
  return async (ctx, next) => {
    const { skipped, finish, runWith } = integration.start(ctx, options)
    if (skipped) {
      await next()
      return
    }
    try {
      await runWith(() => next())
      await finish({ status: /* extract status from ctx */ })
    } catch (error) {
      await finish({ error: error as Error })
      throw error
    }
  }
}

Reference Implementations

• Hono: src/hono/index.ts. c.set('log', logger) + ALS useLogger(), streaming deferral via shouldDeferEmitForResponse, waitUntil detection
• Express: src/express/index.ts. req.log, ALS storage, res.on('finish') for terminal status
• Fastify: src/fastify/index.ts. Fastify hooks (onRequest / onResponse / onError), fastify-plugin wrapper
• Elysia: src/elysia/index.ts. Plugin with .derive({ as: 'global' }), storage.enterWith-style ALS, streaming deferral
• NestJS: src/nestjs/index.ts. EvlogModule.forRoot() / forRootAsync() on top of the manifest
• oRPC: src/orpc/index.ts. evlog() procedure middleware + withEvlog(handler) wrapper
• React Router: src/react-router/index.ts. loggerContext = createContext<AuditableLogger>()
• SvelteKit: src/sveltekit/index.ts. evlog() handle + evlogHandleError() + createEvlogHooks()
• Workers: src/workers/index.ts. defineWorkerFetch / withEvlog, no ALS useLogger() (compat-flag constraint)

For integrations that bind with enterWith(), use createSharedEnterWithStorage from src/shared/asyncStorageScope.ts. Its capability probe runs in a temporary scope with a distinct store, preserving the importer's async context on Bun and Node.

Key Architecture Rules

1. Prefer defineFrameworkIntegration: it handles header normalization, request-id generation, ALS, fork attachment, and waitUntil.
2. Status / error reporting stays framework-side: call finish({ status }) on success and finish({ error }) on failure. finish runs emit + enrich + drain + plugin hooks.
3. Re-throw errors after finish({ error }) so the framework's own error handler still runs.
4. Streaming responses: if the framework can return streaming bodies, defer the emit until the stream closes (shouldDeferEmitForResponse; see Hono and Elysia).
5. Framework SDK is an optional peer dependency: never bundle it.
6. Never duplicate pipeline logic: runEnrichAndDrain is internal to createMiddlewareLogger/finish.
7. Export type helpers for typed context access (e.g., EvlogVariables for Hono).

When to fall back to custom mode

Use createMiddlewareLogger directly (skipping defineFrameworkIntegration) when:

• The middleware doesn't have a clear "request entry / response exit" pair (Next.js App Router server actions, Eve agent turns).
• Logger creation spans multiple lifecycle phases owned by a module system (Nitro plugins + hooks).
• The status is not knowable until after the response stream completes and the framework gives you no hook for it.