fix(start): avoid encoded virtual adapter ids in vite dev

[schiller-manuel]

fixes #7227

Summary by CodeRabbit

• Bug Fixes

  • Fixed virtual module resolution in development environments to prevent reverse proxy failures
  • Improved handling when no serialization adapters are configured with proper fallback mechanisms

• Chores

  • Updated TanStack Start package versions across core and framework packages

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5cdbdfb1-10dc-4ea1-afd8-93b27e8b7306

📥 Commits

Reviewing files that changed from the base of the PR and between abd44dd and a5fbd25.

📒 Files selected for processing (16)

• .changeset/clean-adapters-proxy.md
• packages/start-client-core/package.json
• packages/start-client-core/src/empty-plugin-adapters.ts
• packages/start-client-core/vite.config.ts
• packages/start-plugin-core/src/import-protection/utils.ts
• packages/start-plugin-core/src/rsbuild/plugin.ts
• packages/start-plugin-core/src/rsbuild/virtual-modules.ts
• packages/start-plugin-core/src/utils.ts
• packages/start-plugin-core/src/vite/createVirtualModule.ts
• packages/start-plugin-core/src/vite/import-protection-plugin/plugin.ts
• packages/start-plugin-core/src/vite/plugin.ts
• packages/start-plugin-core/src/vite/serialization-adapters-plugin.ts
• packages/start-plugin-core/tests/importProtection/utils.test.ts
• packages/start-server-core/package.json
• packages/start-server-core/src/empty-plugin-adapters.ts
• packages/start-server-core/vite.config.ts

💤 Files with no reviewable changes (1)

• packages/start-plugin-core/src/import-protection/utils.ts

---

📝 Walkthrough

Walkthrough

This PR fixes TanStack Start virtual module loading failures when deployed behind reverse proxies by eliminating null-byte-encoded virtual IDs, refactoring the serialization adapters plugin with runtime-specific module IDs, and introducing empty-adapter fallbacks when serialization adapters are not configured.

Changes

Serialization Adapters Reverse Proxy Fix

Layer / File(s)	Summary
Centralize escapeRegExp and createIdFilter utilities packages/start-plugin-core/src/utils.ts, packages/start-plugin-core/src/import-protection/utils.ts, packages/start-plugin-core/src/rsbuild/plugin.ts, packages/start-plugin-core/src/vite/..., packages/start-plugin-core/tests/importProtection/utils.test.ts	escapeRegExp is moved to main utils and createIdFilter is added to safely construct ID-matching regexes; all import sites (Vite import-protection, createVirtualModule, Rsbuild, and tests) are updated to source these utilities from the shared location.
Refactor Vite serialization adapters plugin with runtime-specific module IDs packages/start-plugin-core/src/vite/serialization-adapters-plugin.ts, packages/start-plugin-core/src/vite/plugin.ts	Plugin switches from createVirtualModule to explicit Vite plugin with resolveId and load hooks, uses separate client/server virtual module IDs (eliminating null-byte encoding), adds getModuleId() and getRuntime() helpers for clean ID mapping and runtime classification, and conditionally installs the plugin only when serialization adapters are configured.
Conditionally gate adapters in Rsbuild virtual modules packages/start-plugin-core/src/rsbuild/virtual-modules.ts	Introduces hasSerializationAdapters flag and omits pluginAdapters virtual module content, alias entries, and resolve.alias wiring when no serialization adapters exist; uses escapeRegExp when building NormalModuleReplacementPlugin patterns.
Simplify createVirtualModule ID filtering packages/start-plugin-core/src/vite/createVirtualModule.ts	Replaces dynamic RegExp construction with createIdFilter utility for cleaner and safer resolveId.filter and load.filter implementations.
Add empty-adapter fallback packages packages/start-client-core/package.json, packages/start-client-core/vite.config.ts, packages/start-server-core/package.json, packages/start-server-core/src/empty-plugin-adapters.ts, packages/start-server-core/vite.config.ts	Introduces empty serialization adapter files exporting empty adapter arrays and false flags, adds #tanstack-start-plugin-adapters imports to both package.json files pointing to empty-plugin-adapters builds, and updates Vite configs to include empty-adapter entries.
Release documentation .changeset/clean-adapters-proxy.md	Documents patch version bumps and the fix to virtual-module resolution: clean runtime-specific IDs for Vite development and empty-adapter fallback when no adapters are configured.

Possibly Related Issues

• #7227: This PR directly addresses the reverse proxy virtual module loading failure by switching from null-byte-encoded virtual IDs to clean runtime-specific module IDs and providing empty-adapter fallbacks.
• #7418: Related to the same virtual-module ID resolution and reverse proxy compatibility fixes.

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Through proxy mists where modules fear to tread,
Clean IDs now lead where chaos was spread,
No null-bytes encoded in the virtual request,
Empty adapters fallback when none are blessed,
The rabbit hops forward, the reverse proxy's guest! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(start): avoid encoded virtual adapter ids in vite dev' directly describes the main fix: preventing encoded virtual adapter IDs in Vite development, which is the core issue addressed in the changeset.
Linked Issues check	✅ Passed	The changeset comprehensively addresses issue #7227 by implementing Vite dev to resolve clean runtime-specific virtual module IDs instead of browser requests with encoded null-byte virtual IDs, and conditionally handling serialization adapters to prevent reverse proxy failures.
Out of Scope Changes check	✅ Passed	All changes are directly related to resolving the virtual adapter ID encoding issue: moving from fake entries to empty adapters, updating import mappings, conditionally installing serialization plugins, and refactoring virtual module resolution logic.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-7227

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit a5fbd25

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

---

☁️ Nx Cloud last updated this comment at 2026-05-24 22:58:12 UTC

[github-actions]

🚀 Changeset Version Preview

6 package(s) bumped directly, 8 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/react-start	1.168.12 → 1.168.13	Changeset
@tanstack/solid-start	1.168.12 → 1.168.13	Changeset
@tanstack/start-client-core	1.170.3 → 1.170.4	Changeset
@tanstack/start-plugin-core	1.171.5 → 1.171.6	Changeset
@tanstack/start-server-core	1.169.3 → 1.169.4	Changeset
@tanstack/vue-start	1.168.12 → 1.168.13	Changeset
@tanstack/react-start-client	1.168.3 → 1.168.4	Dependent
@tanstack/react-start-rsc	0.1.12 → 0.1.13	Dependent
@tanstack/react-start-server	1.167.8 → 1.167.9	Dependent
@tanstack/solid-start-client	1.168.3 → 1.168.4	Dependent
@tanstack/solid-start-server	1.167.8 → 1.167.9	Dependent
@tanstack/start-static-server-functions	1.167.8 → 1.167.9	Dependent
@tanstack/vue-start-client	1.167.8 → 1.167.9	Dependent
@tanstack/vue-start-server	1.167.8 → 1.167.9	Dependent

[github-actions]

Bundle Size Benchmarks

• Commit: 62c39bba511a
• Measured at: 2026-05-24T22:48:11.100Z
• Baseline source: history:abd44ddf2bfa
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	87.30 KiB	0 B (0.00%)	87.16 KiB	274.03 KiB	75.92 KiB	█▁▁▁▁▁▁▁▁▃▃
react-router.full	90.75 KiB	0 B (0.00%)	90.61 KiB	285.39 KiB	78.80 KiB	█▆▆▆▆▆▆▁▁▂▂
solid-router.minimal	35.53 KiB	0 B (0.00%)	35.41 KiB	106.33 KiB	32.01 KiB	█▁▁▁▁▁▁▁▁▂▂
solid-router.full	40.23 KiB	0 B (0.00%)	40.11 KiB	120.52 KiB	36.19 KiB	▇▇▇▇▇██▂▂▁▁
vue-router.minimal	53.02 KiB	0 B (0.00%)	52.89 KiB	150.35 KiB	47.56 KiB	█████████▁▁
vue-router.full	58.65 KiB	0 B (0.00%)	58.52 KiB	168.08 KiB	52.55 KiB	▁▁▁▁▁▁▁██▅▅
react-start.minimal	101.93 KiB	0 B (0.00%)	101.79 KiB	322.35 KiB	88.25 KiB	▇██████▁▁▁▁
react-start.deferred-hydration	102.66 KiB	0 B (0.00%)	101.81 KiB	323.72 KiB	88.82 KiB	███████▆▆▁▁
react-start.full	105.31 KiB	0 B (0.00%)	105.17 KiB	332.66 KiB	91.06 KiB	█▇▇▇▇▇▇▁▁▁▁
react-start.rsbuild.minimal	99.61 KiB	+3 B (+0.00%)	99.44 KiB	316.79 KiB	85.73 KiB	▆██████▁▁▁▁▂
react-start.rsbuild.full	102.88 KiB	-2 B (-0.00%)	102.71 KiB	327.18 KiB	88.52 KiB	▇██████▁▁▁▁▁
solid-start.minimal	49.63 KiB	0 B (0.00%)	49.50 KiB	152.40 KiB	43.84 KiB	█▇▇▇▇▆▆▁▁▁▁
solid-start.deferred-hydration	52.89 KiB	0 B (0.00%)	49.55 KiB	160.44 KiB	46.71 KiB	███████▇▇▁▁
solid-start.full	55.41 KiB	0 B (0.00%)	55.29 KiB	169.33 KiB	48.81 KiB	███████▁▁▁▁

Current gzip tracks all emitted client JS chunks. Initial gzip tracks only the entry/import graph. Trend sparkline is historical current gzip ending with this PR measurement; lower is better.

[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-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-example-rscs
• 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/arktype-adapter@7484

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@7484

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@7484

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

npm i https://pkg.pr.new/@tanstack/react-start@7484

@tanstack/react-start-client

npm i https://pkg.pr.new/@tanstack/react-start-client@7484

@tanstack/react-start-rsc

npm i https://pkg.pr.new/@tanstack/react-start-rsc@7484

@tanstack/react-start-server

npm i https://pkg.pr.new/@tanstack/react-start-server@7484

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

npm i https://pkg.pr.new/@tanstack/solid-start@7484

@tanstack/solid-start-client

npm i https://pkg.pr.new/@tanstack/solid-start-client@7484

@tanstack/solid-start-server

npm i https://pkg.pr.new/@tanstack/solid-start-server@7484

@tanstack/start-client-core

npm i https://pkg.pr.new/@tanstack/start-client-core@7484

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/@tanstack/start-fn-stubs@7484

@tanstack/start-plugin-core

npm i https://pkg.pr.new/@tanstack/start-plugin-core@7484

@tanstack/start-server-core

npm i https://pkg.pr.new/@tanstack/start-server-core@7484

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

npm i https://pkg.pr.new/@tanstack/start-storage-context@7484

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@7484

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@7484

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

npm i https://pkg.pr.new/@tanstack/vue-start@7484

@tanstack/vue-start-client

npm i https://pkg.pr.new/@tanstack/vue-start-client@7484

@tanstack/vue-start-server

npm i https://pkg.pr.new/@tanstack/vue-start-server@7484

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@7484

commit: a5fbd25

[codspeed-hq]

Merging this PR will not alter performance

✅ 5 untouched benchmarks
⏩ 1 skipped benchmark¹

---

_{Comparing fix-7227 (a5fbd25) with main (abd44dd)}

Footnotes

1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩