fix(tanstack-start): typings for evlogErrorHandler

.changeset/tanstack-evlog-error-handler-types.md

@@ -0,0 +1,5 @@
+---
+"evlog": patch
+---
+
+Align `evlogErrorHandler` with TanStack Start’s `createMiddleware().server()` types: widen `next()` to sync-or-async results, match `RequestServerFn` return typing via `RequestServerResult`, and declare an optional peer on `@tanstack/start-client-core` for accurate declarations ([#235](https://github.com/HugoRCD/evlog/issues/235), [EVL-142](https://linear.app/evlog/issue/EVL-142)).

AGENTS.md

@@ -572,6 +572,8 @@ export const Route = createRootRoute({
 })
 ```
 
+For TypeScript, `evlog` declares an optional peer on `@tanstack/start-client-core` so `evlogErrorHandler` is typed as TanStack’s `RequestServerFn`. Apps using `@tanstack/react-start` already pull that package in for type resolution.
+
 Use `useRequest()` from `nitro/context` to access the logger in routes:
 
 ```typescript

examples/tanstack-start/nitro.config.ts

@@ -1,13 +1,18 @@
 import { defineConfig } from 'nitro'
 import evlog from 'evlog/nitro/v3'
 
+/* `evlog/nitro/v3` may resolve a different `nitro` version than this example's
+ * `nitro-nightly`. Runtime behavior matches; align the module slot for tsc. */
+type NitroUserConfig = Parameters<typeof defineConfig>[0]
+type NitroModuleSlot = NonNullable<NitroUserConfig['modules']>[number]
+
 export default defineConfig({
   experimental: {
     asyncContext: true,
   },
   modules: [
     evlog({
       env: { service: 'tanstack-start-example' },
-    }),
+    }) as NitroModuleSlot,
   ],
 })

examples/tanstack-start/package.json

@@ -8,7 +8,8 @@
   "scripts": {
     "dev": "vite dev --port 3000",
     "build": "vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
     "@tailwindcss/vite": "^4.1.18",

examples/tanstack-start/src/routes/api/admin.ts

@@ -8,6 +8,9 @@ export const Route = createFileRoute('/api/admin')({
     handlers: {
       PUT: async ({ request }) => {
         const req = useRequest()
+        if (!req.context) {
+          throw new Error('Missing Nitro request context')
+        }
         const log = req.context.log as RequestLogger
 
         const body = await request.json() as { resourceId: string, changes: Record<string, unknown> }

examples/tanstack-start/src/routes/api/checkout.ts

@@ -8,6 +8,9 @@ export const Route = createFileRoute('/api/checkout')({
     handlers: {
       POST: async ({ request }) => {
         const req = useRequest()
+        if (!req.context) {
+          throw new Error('Missing Nitro request context')
+        }
         const log = req.context.log as RequestLogger
 
         const body = await request.json() as {

examples/tanstack-start/vite.config.ts

@@ -1,4 +1,4 @@
-import { defineConfig } from 'vite'
+import { defineConfig, type UserConfig } from 'vite'
 import { devtools } from '@tanstack/devtools-vite'
 import tsconfigPaths from 'vite-tsconfig-paths'
 
@@ -8,15 +8,16 @@ import viteReact from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
 import { nitro } from 'nitro/vite'
 
-const config = defineConfig({
-  plugins: [
-    devtools(),
-    nitro({ rollupConfig: { external: [/^@sentry\//] } }),
-    tsconfigPaths({ projects: ['./tsconfig.json'] }),
-    tailwindcss(),
-    tanstackStart(),
-    viteReact(),
-  ],
-})
+/* Plugins come from packages that bundle their own Vite typings (TanStack devtools,
+ * nitro/rolldown, etc.). In a workspace, those are nominally different from this
+ * app's `vite` — assert once here instead of drowning in TS2769 chains. */
+const plugins = [
+  devtools(),
+  nitro({ rollupConfig: { external: [/^@sentry\//] } }),
+  tsconfigPaths({ projects: ['./tsconfig.json'] }),
+  tailwindcss(),
+  tanstackStart(),
+  viteReact(),
+] as UserConfig['plugins']
 
-export default config
+export default defineConfig({ plugins })

packages/evlog/package.json

@@ -293,6 +293,7 @@
     "typecheck": "echo 'Typecheck handled by build'"
   },
   "devDependencies": {
+    "@tanstack/start-client-core": "^1.167.7",
     "acorn": "^8.16.0",
     "@codspeed/vitest-plugin": "^5.2.0",
     "@nestjs/common": "^11.1.17",
@@ -336,7 +337,8 @@
     "@nestjs/common": ">=11.1.17",
     "react-router": ">=7.13.2",
     "vite": "^7.0.0 || ^8.0.0",
-    "ai": ">=6.0.142"
+    "ai": ">=6.0.142",
+    "@tanstack/start-client-core": "^1.161.0"
   },
   "peerDependenciesMeta": {
     "@nuxt/kit": {
@@ -383,6 +385,9 @@
     },
     "ai": {
       "optional": true
+    },
+    "@tanstack/start-client-core": {
+      "optional": true
     }
   }
 }

packages/evlog/src/nitro-v3/middleware.ts

@@ -1,6 +1,6 @@
+import type { RequestServerResult } from '@tanstack/start-client-core'
 import type { RequestLogger } from '../types'
 import { EvlogError } from '../error'
-import { serializeEvlogErrorResponse } from '../nitro'
 
 /**
  * Server middleware handler that catches EvlogError and returns a structured JSON response.
@@ -23,10 +23,19 @@ import { serializeEvlogErrorResponse } from '../nitro'
  * ```
  */
 
-export async function evlogErrorHandler<T>(nextOrOptions: ((...args: any[]) => Promise<T>) | { next: (...args: any[]) => Promise<T> }): Promise<T> {
+/**
+ * TanStack's `RequestServerNextFn` may return synchronously or as a `Promise`, and uses a
+ * typed `options` argument. A rest-args `any[]` signature keeps `RequestServerNextFn`
+ * assignable under `strictFunctionTypes`. The return type matches `createMiddleware().server()`.
+ */
+type EvlogServerMiddlewareNext = (...args: any[]) => unknown | Promise<unknown>
+
+export async function evlogErrorHandler(
+  nextOrOptions: EvlogServerMiddlewareNext | { next: EvlogServerMiddlewareNext },
+): Promise<RequestServerResult<any, any, any> | Response> {
   const next = typeof nextOrOptions === 'function' ? nextOrOptions : nextOrOptions.next
   try {
-    return await next()
+    return (await Promise.resolve(next())) as RequestServerResult<any, any, any>
   } catch (error: unknown) {
     if (error instanceof EvlogError || (error && typeof error === 'object' && (error as Error).name === 'EvlogError')) {
       const evlogError = error as EvlogError