feat(library): add evlog observability library (#110)

* feat(library): add evlog observability library

Adds evlog (wide-event structured logging) as a new per-app library
option under a new Observability category. Supports Next.js, Hono,
TanStack Start, and Node stacks.

- META entry with evlog ^2.11.0 and nitro devDep scoped to tanstack-start
- Next.js: lib/evlog.ts (createEvlog + createInstrumentation),
  instrumentation.ts (defineNodeInstrumentation), proxy.ts rewrites
  return value through evlogMiddleware when selected
- Hono: initLogger + evlog() middleware wired into src/app.ts, replaces
  hono/logger and adds EvlogVariables typing
- TanStack Start: nitro.config.ts module registration with
  experimental.asyncContext, __root.tsx wires evlogErrorHandler via
  server middleware
- Node: initLogger + createLogger wire-up in src/index.ts
- Composes cleanly with better-auth in Next.js proxy
- Full integration test covering all four stacks, turborepo multi-app,
  and no-evlog regression

* fix(library): improve evlog Hono error handler and simplify Node wire-up

- Hono: app.onError uses c.get('log').error(err) + parseError for
  structured error responses instead of raw console.error
- Node: remove demo createLogger/set/emit, keep only initLogger + log.info
  for minimal wire-up consistent with other stacks
- Add test for Hono structured error handling

* fix(library): remove captureOutput from evlog instrumentation

* fix(library): move instrumentation.ts into src/ for Next.js convention

Next.js looks for instrumentation.ts inside src/ when using the src/
directory convention. Fixes double output caused by incorrect file
placement.

* docs(modules): add evlog observability documentation page

Adds Observability category to module docs sidebar and evlog.mdx
covering per-stack wire-up: Next.js (factory + instrumentation +
proxy middleware), Hono (initLogger + evlog middleware + parseError),
TanStack Start (nitro module + error handler), and Node (initLogger).

Author: plvo

apps/cli/src/__meta__.ts

@@ -324,6 +324,20 @@ export const META: Meta = {
       support: { stacks: ['hono'] },
       packageJson: {},
     },
+    evlog: {
+      label: 'evlog',
+      hint: 'Wide-event structured logging with drains and sampling',
+      category: 'Observability',
+      support: { stacks: ['nextjs', 'hono', 'tanstack-start', 'node'] },
+      packageJson: {
+        dependencies: {
+          evlog: '^2.11.0',
+        },
+        devDependencies: {
+          nitro: $when({ stack: 'tanstack-start' }, '^3.0.260311-beta'),
+        },
+      },
+    },
   },
 
   project: {

apps/cli/templates/libraries/evlog/nitro.config.ts.tanstack-start.hbs

@@ -0,0 +1,13 @@
+import { defineConfig } from 'nitro';
+import evlog from 'evlog/nitro/v3';
+
+export default defineConfig({
+  experimental: {
+    asyncContext: true,
+  },
+  modules: [
+    evlog({
+      env: { service: '{{appName}}' },
+    }),
+  ],
+});

apps/cli/templates/libraries/evlog/src/instrumentation.ts.nextjs.hbs

@@ -0,0 +1,3 @@
+import { defineNodeInstrumentation } from 'evlog/next/instrumentation';
+
+export const { register, onRequestError } = defineNodeInstrumentation(() => import('./lib/evlog'));

apps/cli/templates/libraries/evlog/src/lib/evlog.ts.nextjs.hbs

@@ -0,0 +1,10 @@
+import { createEvlog } from 'evlog/next';
+import { createInstrumentation } from 'evlog/next/instrumentation';
+
+export const { withEvlog, useLogger, log, createError } = createEvlog({
+  service: '{{appName}}',
+});
+
+export const { register, onRequestError } = createInstrumentation({
+  service: '{{appName}}',
+});

apps/cli/templates/stack/hono/src/app.ts.hbs

@@ -1,11 +1,26 @@
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
+{{#unless (hasLibrary "evlog")}}
 import { logger } from 'hono/logger';
+{{/unless}}
 import { timeout } from 'hono/timeout';
+{{#if (hasLibrary "evlog")}}
+import { initLogger, parseError } from 'evlog';
+import { evlog, type EvlogVariables } from 'evlog/hono';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
 
-const app = new Hono();
+initLogger({
+  env: { service: '{{appName}}' },
+});
+{{/if}}
+
+const app = new Hono{{#if (hasLibrary "evlog")}}<EvlogVariables>{{/if}}();
 
+{{#if (hasLibrary "evlog")}}
+app.use(evlog());
+{{else}}
 app.use(logger());
+{{/if}}
 app.use(timeout(15000));
 
 app.use(
@@ -42,6 +57,19 @@ app.get('/health/:id', (c) => {
 });
 
 app.onError((err, c) => {
+  {{#if (hasLibrary "evlog")}}
+  c.get('log').error(err);
+  const parsed = parseError(err);
+  return c.json(
+    {
+      ok: false,
+      message: parsed.message,
+      why: parsed.why,
+      fix: parsed.fix,
+    },
+    (parsed.status || 500) as ContentfulStatusCode,
+  );
+  {{else}}
   console.error('Error:', err);
   return c.json(
     {
@@ -51,6 +79,7 @@ app.onError((err, c) => {
     },
     500,
   );
+  {{/if}}
 });
 
 export default app;

apps/cli/templates/stack/nextjs/src/proxy.ts.hbs

@@ -1,4 +1,9 @@
+{{#if (hasLibrary "evlog")}}
+import type { NextRequest } from 'next/server';
+import { evlogMiddleware } from 'evlog/next';
+{{else}}
 import { type NextRequest, NextResponse } from 'next/server';
+{{/if}}
 {{#if (hasLibrary "better-auth")}}
 import { headers } from 'next/headers';
 {{#if (isMono)}}
@@ -8,6 +13,10 @@ import { auth } from '@/lib/auth/auth';
 {{/if}}
 {{/if}}
 
+{{#if (hasLibrary "evlog")}}
+const withEvlog = evlogMiddleware();
+{{/if}}
+
 export default async function proxy(request: NextRequest) {
   const { pathname } = request.nextUrl;
 
@@ -21,7 +30,11 @@ export default async function proxy(request: NextRequest) {
   console.log(`PROXY "${pathname}"`);
   {{/if}}
 
+  {{#if (hasLibrary "evlog")}}
+  return await withEvlog(request);
+  {{else}}
   return NextResponse.next();
+  {{/if}}
 }
 
 export const config = {

apps/cli/templates/stack/node/src/index.ts.hbs

@@ -1 +1,11 @@
+{{#if (hasLibrary "evlog")}}
+import { initLogger, log } from 'evlog';
+
+initLogger({
+  env: { service: '{{appName}}' },
+});
+
+log.info({ action: 'startup' });
+{{else}}
 console.log('Hello from {{appName}}');
+{{/if}}

apps/cli/templates/stack/tanstack-start/src/routes/___root.tsx.hbs

@@ -1,6 +1,10 @@
 /// <reference types="vite/client" />
 import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
 import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
+{{#if (hasLibrary "evlog")}}
+import { createMiddleware } from '@tanstack/react-start'
+import { evlogErrorHandler } from 'evlog/nitro/v3'
+{{/if}}
 
 import appCss from '../styles.css?url'
 
@@ -25,6 +29,11 @@ export const Route = createRootRoute({
       },
     ],
   }),
+  {{#if (hasLibrary "evlog")}}
+  server: {
+    middleware: [createMiddleware().server(evlogErrorHandler)],
+  },
+  {{/if}}
   shellComponent: RootDocument,
 })