From 3291457cf923c4f791cce9dd5bb16e66deca6170 Mon Sep 17 00:00:00 2001 From: "evlogai[bot]" Date: Thu, 10 Sep 2026 20:59:05 +0000 Subject: [PATCH] docs: state the framework-page contract per integration tier The old sentence claimed every framework integration exposes evlog(), useLogger() and log.fork(). The source contradicts it: fork is wired only via defineFrameworkIntegration (elysia, express, fastify, hono, nestjs, next, orpc, react-router, sveltekit, workers), nuxt and nitro are event-bound with no fork, and astro, aws-lambda and standalone are guide-level on the core createLogger/createRequestLogger API. A reviewer applying the old line literally would flag correct pages as incomplete. --- .../write-evlog-content/references/surfaces/docs.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.agents/skills/write-evlog-content/references/surfaces/docs.md b/.agents/skills/write-evlog-content/references/surfaces/docs.md index b3245b86b..675ddf5b5 100644 --- a/.agents/skills/write-evlog-content/references/surfaces/docs.md +++ b/.agents/skills/write-evlog-content/references/surfaces/docs.md @@ -35,9 +35,15 @@ next a link out, on the thing they will need after this A page in the wrong directory is a structural finding, not a wording one. -## Integration pages carry the same contract +## Integration pages carry the contract of their tier -Every framework integration exposes `evlog()`, `useLogger()`, `log.fork()`, and the full `BaseEvlogOptions` surface, alongside the framework-native accessor. A framework page that documents only the native accessor is incomplete, and one that documents only `useLogger()` misses the idiomatic path. `evlog/workers` is the documented exception: no `useLogger()`, and the logger arrives as the handler's fourth argument. +The contract follows how the integration is built, so check the tier before flagging a page as incomplete: + +- First-class integrations built on `defineFrameworkIntegration` (elysia, express, fastify, hono, next, nestjs, orpc, react-router, sveltekit, workers) take the full `BaseEvlogOptions` surface and expose a request-bound logger, but the entry point's own accessor names differ: `evlog()` and `withEvlog()` on orpc, `evlog()` on elysia, express, fastify, hono, react-router and sveltekit, `createEvlog()` and `evlogMiddleware()` on next, `EvlogModule` on nestjs, `withEvlog()` and `createWorkersLogger()` on workers. A framework page that documents only the framework-native accessor is incomplete, and one that documents only `useLogger()` misses the idiomatic path. +- `log.fork()` is wired where the request scope is `AsyncLocalStorage`-backed: every first-class integration except workers, which must stay free of `node:async_hooks`. +- Nuxt and Nitro are event-bound: `useLogger(event)`, and no `log.fork()`. Documenting `log.fork()` there claims an API that does not exist. +- Astro, AWS Lambda and standalone are guide-level on the core API (`initLogger`, `createLogger`, `createRequestLogger`): no `evlog()`, no `useLogger()`, no `log.fork()`. Do not add them to these pages. +- `evlog/workers` delivers the logger as the handler's fourth argument, not through `useLogger()`. ## Code blocks