fix: add serverFnMeta as optional to request middleware

[schiller-manuel]

Summary by CodeRabbit

• New Features
  • Request middleware now captures and exposes server function metadata (id, name, filename) through loader data and route context
  • Full server function metadata is available server-side while client-side access is appropriately restricted for security and isolation
  • Developers can now track which server functions are being invoked and access their details throughout the application lifecycle

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces server-side request middleware that captures server function metadata (id, name, filename) and propagates it through route context, loaders, and components. Changes extend the RequestServerOptions public API to include optional serverFnMeta and update E2E tests and type definitions to validate metadata flow.

Changes

Cohort / File(s)	Summary
E2E Request Middleware Implementation e2e/react-start/server-functions/src/routes/middleware/function-metadata.tsx	Introduces two new server-side middlewares (requestMetadataMiddleware, pageRequestMiddleware) that capture server function metadata into route context. Extends route configuration to expose pageRequestServerFnMeta via beforeLoad. Updates RouteComponent to access and display captured metadata (id, name, filename) from both request and loader paths via Route.useRouteContext. Server function getMetadataFn now returns requestCapturedMeta field.
E2E Test Coverage Expansion e2e/react-start/server-functions/tests/server-functions.spec.ts	Expands test assertions to validate metadata propagation across loader, client, and request middleware paths. Verifies page requests return undefined serverFnMeta, confirms request middleware captures full metadata (id, name, filename) for both server function calls and client calls, and adds new test IDs for request middleware metadata validation.
RequestServerOptions API Extension packages/start-client-core/src/createMiddleware.ts	Extends RequestServerOptions interface with optional serverFnMeta?: ServerFnMeta property, present only for server function calls (undefined for regular page requests).
Type Definition Tests packages/start-client-core/src/tests/createServerMiddleware.test-d.ts	Adds ServerFnMeta type import and updates test scenarios to include optional serverFnMeta property in server callback options across multiple middleware configuration variants.

Sequence Diagram

sequenceDiagram
    participant Client
    participant RequestMiddleware
    participant RouteContext
    participant RouteLoader
    participant RouteComponent

    Client->>RequestMiddleware: HTTP request (server function call)
    RequestMiddleware->>RequestMiddleware: Capture serverFnMeta<br/>(id, name, filename)
    RequestMiddleware->>RouteContext: Store as requestCapturedMeta
    RouteContext->>RouteLoader: Pass requestCapturedMeta<br/>via loaderData
    RouteContext->>RouteComponent: Expose pageRequestServerFnMeta<br/>via Route.useRouteContext
    RouteComponent->>RouteComponent: Display metadata from<br/>loader + route context
    RouteComponent->>Client: Render with captured metadata

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~28 minutes

Possibly related PRs

• fix: pass in request when requestMiddleware is used in combination wi… #5390: Modifies server request propagation into middleware/start context, ensuring request-scoped metadata is available to request middlewares.
• fix: correct compiler plugin order, only handle createMiddleware in a … #6163: Changes compiler-plugin handling of createMiddleware by removing client-side transforms, related to the public API surface modifications in this PR.

Suggested labels

package: start-client-core

Poem

🐰 A rabbit hops through metadata streams,
Request by request, middleware dreams,
Capturing names, IDs, and traces so bright,
Through loaders and context, the data takes flight!
From server to client, the flow runs divine,
Middleware magic—your metadata's mine! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding serverFnMeta as optional to request middleware, which is the central modification across multiple files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d87a631 and 3233b64.

📒 Files selected for processing (4)

• e2e/react-start/server-functions/src/routes/middleware/function-metadata.tsx
• e2e/react-start/server-functions/tests/server-functions.spec.ts
• packages/start-client-core/src/createMiddleware.ts
• packages/start-client-core/src/tests/createServerMiddleware.test-d.ts

🧰 Additional context used

📓 Path-based instructions (2)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use TypeScript strict mode with extensive type safety for all code

Files:

• packages/start-client-core/src/createMiddleware.ts
• e2e/react-start/server-functions/tests/server-functions.spec.ts
• e2e/react-start/server-functions/src/routes/middleware/function-metadata.tsx
• packages/start-client-core/src/tests/createServerMiddleware.test-d.ts

**/*.{js,ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Implement ESLint rules for router best practices using the ESLint plugin router

Files:

• packages/start-client-core/src/createMiddleware.ts
• e2e/react-start/server-functions/tests/server-functions.spec.ts
• e2e/react-start/server-functions/src/routes/middleware/function-metadata.tsx
• packages/start-client-core/src/tests/createServerMiddleware.test-d.ts

🧠 Learnings (1)

📚 Learning: 2025-12-24T22:47:44.320Z

Learnt from: schiller-manuel
Repo: TanStack/router PR: 6211
File: e2e/react-start/i18n-paraglide/src/server.ts:6-6
Timestamp: 2025-12-24T22:47:44.320Z
Learning: In TanStack Router projects using `inlang/paraglide-js`, the callback passed to `paraglideMiddleware` should use `() => handler.fetch(req)` (referencing the outer `req`) instead of `({ request }) => handler.fetch(request)`. This is intentional because the router needs the untouched URL to perform its own rewrite logic with `deLocalizeUrl`/`localizeUrl`. The middleware's processed request would delocalize the URL and interfere with the router's rewrite handling.

Applied to files:

• e2e/react-start/server-functions/tests/server-functions.spec.ts
• e2e/react-start/server-functions/src/routes/middleware/function-metadata.tsx

🧬 Code graph analysis (2)

packages/start-client-core/src/createMiddleware.ts (2)

packages/start-client-core/src/constants.ts (1)

• ServerFnMeta (83-88)

packages/start-client-core/src/index.tsx (1)

• ServerFnMeta (99-99)

e2e/react-start/server-functions/src/routes/middleware/function-metadata.tsx (2)

packages/start-client-core/src/createMiddleware.ts (1)

• createMiddleware (29-62)

e2e/react-start/server-functions/src/routes/middleware/index.tsx (1)

• Route (3-5)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Test
• GitHub Check: Preview

🔇 Additional comments (10)

packages/start-client-core/src/createMiddleware.ts (1)

751-762: LGTM! Well-documented optional property addition.

The serverFnMeta property is correctly typed as optional with clear JSDoc explaining when it's present (server function calls) versus undefined (regular page requests). This aligns with the existing pattern where FunctionMiddlewareServerFnOptions has a non-optional serverFnMeta: ServerFnMeta on line 515, differentiating function middleware (always has metadata) from request middleware (conditionally has metadata).

packages/start-client-core/src/tests/createServerMiddleware.test-d.ts (2)

6-6: LGTM! Type import correctly added.

The ServerFnMeta type import from ../constants is properly placed with the other type imports and is required for the updated type expectations in the request middleware tests.

---

656-677: Type tests comprehensively updated for request middleware.

The type expectations correctly reflect that serverFnMeta is optional in RequestServerOptions. All request middleware test scenarios are consistently updated to include serverFnMeta?: ServerFnMeta in the expected options type structure.

e2e/react-start/server-functions/tests/server-functions.spec.ts (1)

761-884: LGTM! Comprehensive E2E test coverage for the new serverFnMeta propagation.

The test correctly verifies:

1. Page requests receive undefined serverFnMeta (line 780)
2. Request middleware captures full metadata (id, name, filename) for server function calls (lines 829-835)
3. Both SSR loader and client-side calls receive consistent request middleware metadata

The use of '$undefined' as a sentinel value effectively proves the middleware executed rather than silently failing.

e2e/react-start/server-functions/src/routes/middleware/function-metadata.tsx (6)

5-16: LGTM! Clean request middleware implementation.

The requestMetadataMiddleware correctly captures serverFnMeta from the options and stores it in the context. This middleware will receive full ServerFnMeta (id, name, filename) for server function calls since it runs server-side.

---

18-31: LGTM! Effective sentinel value pattern for testing.

Using '$undefined' string as a sentinel value is a good testing pattern—it proves the middleware executed and actively passed data through, rather than the value being undefined due to the middleware not running at all.

---

33-50: LGTM! Proper middleware composition.

The function middleware correctly:

1. Chains requestMetadataMiddleware via .middleware([...])
2. Propagates requestCapturedMeta from the request middleware context to the server context

This ensures the request-level metadata is available in the handler's context.

---

52-67: LGTM! Handler returns all three metadata sources.

The handler correctly returns the complete metadata picture:

• serverMeta: Full metadata from server middleware
• clientCapturedMeta: ID-only from client middleware
• requestCapturedMeta: Full metadata from request middleware

---

96-130: LGTM! Component correctly accesses route context.

The component properly uses Route.useRouteContext() to access pageRequestServerFnMeta that was populated by beforeLoad. The conditional rendering handles both string ('$undefined') and object cases appropriately.

---

69-94: The serverContext type is fully inferred and properly typed by TanStack Router.

The serverContext parameter in beforeLoad is declared as optional in the BeforeLoadContextOptions interface from @tanstack/react-start. TypeScript correctly infers its type through the generic parameters passed to createFileRoute, combining ResolveAllServerContext (from middleware) and ExtractHandlersContext (from the GET handler). The optional chaining (serverContext?.pageRequestServerFnMeta) is the correct and necessary pattern for accessing properties on an optional value. No explicit type annotation or additional type safety measures are needed.

Likely an incorrect or invalid review comment.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 3233b64

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	15m 35s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	35s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-01-11 23:42:41 UTC

[pkg-pr-new]

More templates

• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsc
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query
• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc
• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc

@tanstack/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@6366

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@6366

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@6366

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@6366

@tanstack/react-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@6366

@tanstack/react-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@6366

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@6366

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@6366

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@6366

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@6366

@tanstack/router-cli

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@6366

@tanstack/router-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@6366

@tanstack/router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@6366

@tanstack/router-devtools-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@6366

@tanstack/router-generator

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@6366

@tanstack/router-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@6366

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@6366

@tanstack/router-utils

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@6366

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@6366

@tanstack/solid-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@6366

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@6366

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-ssr-query@6366

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@6366

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@6366

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@6366

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@6366

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-fn-stubs@6366

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@6366

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@6366

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@6366

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@6366

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@6366

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@6366

@tanstack/vue-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router@6366

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-devtools@6366

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-ssr-query@6366

@tanstack/vue-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start@6366

@tanstack/vue-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-client@6366

@tanstack/vue-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-server@6366

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@6366

commit: 3233b64