fix(start): allow request middleware to return Response

[JBR-0100]

Fixes #5846. This change allows RequestMiddleware to return a Response object directly, as expected by the issue report. Updated type tests to reflect this change.

Summary by CodeRabbit

• New Features

  • Middleware server functions can now return a Response object directly (sync or Promise) in addition to previous result types, allowing more flexible response handling.

• Tests

  • Added tests covering direct Response returns (sync and async) to validate the widened return behavior.

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

[coderabbitai]

Walkthrough

The PR widens the RequestMiddlewareServerFnResult type to accept Response (sync or Promise) in addition to RequestServerResult, and adds type tests confirming middleware handlers may return Response directly or via Promise.

Changes

Cohort / File(s)	Summary
Type definition update packages/start-client-core/src/createMiddleware.ts	Expanded RequestMiddlewareServerFnResult<TRegister, TMiddlewares, TServerContext> to include Response and Promise<Response> alongside existing RequestServerResult variants.
Type validation tests packages/start-client-core/src/tests/createServerMiddleware.test-d.ts	Added tests asserting middleware can return a Response directly, a Promise<Response>, and a synchronous Response; adjusted typings accordingly.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Focus review on the updated union type in createMiddleware.ts.
• Verify the three new type tests compile and correctly cover sync/async Response returns.

Possibly related PRs

• fix: Make serverFn union response type distributive #5720: Similar change to allow Response in server-related return-type unions.
• fix: Reexport missing request middleware types #5267: Re-exports or related uses of the widened middleware/server return types.

Suggested reviewers

• chorobin

Poem

🐰 I hopped through types both old and new,
Found a gap where Responses slipped through.
Now sync or promised, both are fine,
Middleware returns sing in line. 🥕✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: allowing request middleware to return Response objects, which directly reflects the code modifications.
Linked Issues check	✅ Passed	The PR successfully addresses issue #5846 by updating RequestMiddlewareServerFnResult type to accept Response as a valid return value, with corresponding type tests added.
Out of Scope Changes check	✅ Passed	All changes are directly related to the PR objective: expanding middleware typing to support Response returns and adding comprehensive type tests for the new functionality.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 326029a and 5aa86f1.

📒 Files selected for processing (2)

• packages/start-client-core/src/createMiddleware.ts (1 hunks)
• packages/start-client-core/src/tests/createServerMiddleware.test-d.ts (4 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/start-client-core/src/createMiddleware.ts

🧰 Additional context used

📓 Path-based instructions (1)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use TypeScript strict mode with extensive type safety throughout the codebase

Files:

• packages/start-client-core/src/tests/createServerMiddleware.test-d.ts

⏰ 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). (3)

• GitHub Check: Preview
• GitHub Check: Test
• GitHub Check: autofix

🔇 Additional comments (2)

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

666-674: LGTM! Type expectations properly updated to accept Response.

The type expectations have been consistently updated across all request-type middleware tests to include | Response as a valid return type. This correctly reflects the PR objective of allowing middleware to return Response objects directly while maintaining backward compatibility with the structured result format.

Also applies to: 691-699, 717-725, 743-751

---

757-805: LGTM! Comprehensive test coverage for Response return types.

The three new test cases thoroughly validate the expanded middleware signature:

• Conditional Response return demonstrates early-exit scenarios (e.g., auth checks)
• Promise validates async Response handling
• Synchronous Response validates immediate returns with custom status and headers

These tests properly exercise the type system to ensure middleware can return Response in all expected patterns.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[nx-cloud]

🤖 Nx Cloud AI Fix Eligible

An automatically generated fix could have helped fix failing tasks for this run, but Self-healing CI is disabled for this workspace. Visit workspace settings to enable it and get automatic fixes in future runs.

_{To disable these notifications, a workspace admin can disable them in workspace settings.}

---

View your CI Pipeline Execution ↗ for commit 5aa86f1

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

---

☁️ Nx Cloud last updated this comment at 2025-12-02 21:19:42 UTC

[pkg-pr-new]

More templates

• 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
• 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-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-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/arktype-adapter

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

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@6006

@tanstack/eslint-plugin-router

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@6006

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/zod-adapter

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

commit: 5aa86f1

[birkskyum]

@JBR-0100 , the CI failed

[JBR-0100]

Just checked - the tests are passing locally on my end. Could you share what specific test failed in CI? I can take a look and fix it.

[JBR-0100]

Looking at the failures, they're all Solid Start related (builds + e2e tests), while React Start tests passed. My changes are only to the types in start-client-core (allowing Response as a return type), which shouldn't cause runtime failures.

The type change itself looks correct - just allows RequestMiddleware to return Response directly. Could this be a build order or caching issue in CI? The tests pass locally on my machine.