Vite HMR blank page when editing `__root.tsx` (Solid SSR) #6331
Send to my agentWhich project does this relate to?#
Router
Describe the bug#
Editing __root.tsx triggers HMR but renders blank page with client error:
Warning: template2 is not a function
Server-side stack trace:
RunnerError
at reviveInvokeError (vite/dist/node/module-runner.js:476:64)
at Object.invoke (vite/dist/node/module-runner.js:549:11)
at ModuleRunner.getModuleInformation (vite/dist/node/module-runner.js:1086:7)
at request (vite/dist/node/module-runner.js:1103:83)
at /src/routeTree.gen.ts:11:1 ← import { Route as rootRouteImport } from './routes/__root'
at ESModulesEvaluator.runInlinedModule (vite/dist/node/module-runner.js:913:3)
at ModuleRunner.directRequest (vite/dist/node/module-runner.js:1146:59)
at ModuleRunner.cachedRequest (vite/dist/node/module-runner.js:1053:73)
at /src/router.tsx:4:1 ← import { routeTree } from '~/routeTree.gen'
at ESModulesEvaluator.runInlinedModule (vite/dist/node/module-runner.js:913:3)
status: 500
HMR works correctly on all other route files.
Your Example Website or App#
n/a
Steps to Reproduce the Bug or Issue#
- Create TanStack Start (Solid) app
pnpm dev- Edit
__root.tsx(e.g. change some text) - Observe: Blank page, console shows
template2 is not a function - Compare: Edit
index.tsx→ HMR works fine
Expected behavior#
Expected: Either successful HMR or graceful full reload Actual: Blank page requiring manual refresh
Screenshots or Videos#
No response
Platform#
- Router / Start Version: 1.145.11
- OS: macOS
- Browser: Chrome
- Browser Version: 144.0
- Bundler: Vite
- Bundler Version: 7.3.0
Additional context#
No response
@brenelz yeah, with a minimal setup, I don't see the page turning blank anymore, after saving changes to
__root.tsx.But, I do see that the title turns blank. In the example code, the document has a title set via
head(), but after modifying__root.tsx, the<title>tag gets removed from DOM, which suggests that there's some reloading or re-execution going on.Interestingly, after the first edit, the page content does get updated, i.e. HMR works partially (with a broken title); but, any subsequent edits can no longer trigger any content update.
And again, the browser console consistently logs the warning message from Solid:
@solid-refresh:128 Warning: template2 is not a function warning @ tiny-warning.esm.js?v=8d35ec39:9 onCatch @ Matches.jsx:65 fallback @ CatchBoundary.jsx:15 (anonymous) @ chunk-C2GCMIFK.js?v=8d35ec39:1583 untrack @ chunk-C2GCMIFK.js?v=8d35ec39:462 ErrorBoundary.createMemo.name @ chunk-C2GCMIFK.js?v=8d35ec39:1583 runComputation @ chunk-C2GCMIFK.js?v=8d35ec39:734 updateComputation @ chunk-C2GCMIFK.js?v=8d35ec39:717 runTop @ chunk-C2GCMIFK.js?v=8d35ec39:827 runQueue @ chunk-C2GCMIFK.js?v=8d35ec39:901 completeUpdates @ chunk-C2GCMIFK.js?v=8d35ec39:856 runUpdates @ chunk-C2GCMIFK.js?v=8d35ec39:845 completeUpdates @ chunk-C2GCMIFK.js?v=8d35ec39:896 runUpdates @ chunk-C2GCMIFK.js?v=8d35ec39:845 writeSignal @ chunk-C2GCMIFK.js?v=8d35ec39:690 setter @ chunk-C2GCMIFK.js?v=8d35ec39:224 patchComponent @ @solid-refresh:128 patchComponents @ @solid-refresh:147 patchRegistry @ @solid-refresh:190 ...Also do you know if the react version works?
@brenelz just added a minimal react example similar to the solid one, and yes, react hmr works when modifying
__root.tsx!schiller-manuel(GitHub profile, opens in a new tab) added labelspackage: solid-router
schiller-manuel(GitHub profile, opens in a new tab) added labelspackage: solid-start
Ok I think I have a fix. Can you add this at the top of __root.tsx?
// @refresh reloadIi noticed it does it in solid start for the entry files
https://github.com/solidjs/solid-start/blob/main/apps/fixtures/basic/src/entry-server.tsx
Just tried your found @brenelz and it worked pretty well; it forces a page reload on file change. The dev server consoles prints the following info btw:
3:53:08 PM [vite] (client) hmr update /src/tailwind.css?direct, /src/routes/__root.tsx 3:53:08 PM [vite] (ssr) page reload src/routes/__root.tsx 3:53:08 PM [vite] (client) hmr invalidate /src/routes/__root.tsx 3:53:08 PM [vite] (client) page reload src/routes/__root.tsx 3:53:19 PM [vite] (client) hmr update /src/tailwind.css?direct, /src/routes/__root.tsx 3:53:19 PM [vite] (ssr) page reload src/routes/__root.tsx 3:53:19 PM [vite] (client) hmr invalidate /src/routes/__root.tsx 3:53:19 PM [vite] (client) page reload src/routes/__root.tsxBut ideally, Solid's behavior when working with Vite HMR can catch up with React.
Seeing this same root cause but with a broader symptom: every save to a file under
src/routes/**/*.tsx(not just__root.tsx) triggers a full program reload in a TanStack Start + Solid app.Terminal on save:
[vite] (client) page reload src/routes/_authed/triage.tsx [vite] (ssr) page reload src/routes/_authed/triage.tsx (x2) [vite] program reloadTraced it through the plugin source. The HMR-enabling compiler plugins are only wired for React:
@tanstack/router-plugin/src/core/code-splitter/plugins/framework-plugins.tsswitch (opts.targetFramework) { case 'react': { if (opts.addHmr) { return [ createReactRefreshIgnoredRouteExportsPlugin({ hotExpression: opts.hmrHotExpression }), createReactRefreshRouteComponentsPlugin(), createReactStableHmrSplitRouteComponentsPlugin({ hotExpression: opts.hmrHotExpression }), ] } return undefined } default: return undefined // ← Solid falls through here }Because Solid returns
undefined, the code splitter never injects ahot.accepthandler into transformed route files, so every route change bubbles to the root and Vite falls back tofull-reload.The React equivalent of this bug was tracked as #6195 and fixed in late Dec 2025 by adding the three
react-refresh-*plugins above. No Solid equivalent has been added — #6331 is currently the only open tracking issue, and it's scoped just to__root.tsx, so it may undersell the scope.Of the three React plugins, two are generically applicable to any framework whose refresh runtime needs top-level component declarations (component hoisting, stable lazy-wrapper identity via
hot.data). The third (react-refresh-ignored-route-exports) uses React-specific globals and would need asolid-refreshanalog.Happy to help scope or prototype if useful. Reproducing on
@tanstack/solid-start@1.167.x/@tanstack/solid-router@1.168.x/ Vite 8.I struggle a bit to reproduce both the "reload program" and the page turning blank, but I did some work here on the router-plugin to add solid, that maybe resolves it?
https://github.com/TanStack/router/commit/b86b06125364a2ec8207f599fb5a5130f9d16cc7
And another fix for route matching here:
https://github.com/TanStack/router/commit/a1c52f100a315b7b60220b98b4fe9b8c3acd81fc
I struggle a bit to reproduce both the "reload program" and the page turning blank, but I did some work here on the router-plugin to add solid, that maybe resolves it?
And another fix for route matching here:
Thanks @birkskyum — appreciate the quick turnaround. I tested both commits end-to-end against the same Solid + TanStack Start setup from my earlier reproducer.
Setup notes for anyone following along: the branch tip currently sits at
a1c52f1, butb86b061was reverted on it (b0024d6). To test the intended fix I had to checkoutb86b061and cherry-pick the regex fix froma1c52f1on top, thenpnpm packthe affected packages and consume them via overrides in my app.Verified the fix is active:
node_modules/@tanstack/router-plugin/dist/esm/core/code-splitter/plugins/framework-plugins.jsincludescase "solid":returningcreateRefreshRouteComponentsPlugin()+createStableHmrSplitRouteComponentsPlugin().curlon a route file at dev time shows theimport.meta.hot.accept(...)block fromvite-adapter.tscorrectly appended aftercreateFileRoute(...). So the inject path is wired and runs for Solid.
But the original symptom still reproduces. Editing any file under
src/routes/**/*.tsxstill triggers:[vite] (client) page reload src/routes/<file>.tsx [vite] (ssr) page reload src/routes/<file>.tsx [vite] program reloadI think there are two remaining gaps:
No Solid analog of
react-refresh-ignored-route-exports. The Reactcasereturns three plugins; the new Solidcasereturns only two. Without an "ignored route exports" plugin,solid-refresh(viavite-plugin-solid) sees the non-componentRoute = createFileRoute(...)export, treats the module as non-refreshable, and invalidates it — which is what produces thepage reloadon the client side even though ourimport.meta.hot.acceptis sitting right there. You called this out in your earlier comment ("would need asolid-refreshanalog"); the fix as merged does not address it.solid-refreshdoesn't expose the same explicitregister/ignoreAPI asreact-refresh, but I think it can be approximated by wrapping the route module in a// @refresh skip/// @refresh reloadannotation per route file, or by directly emitting ahot.invalidate()-suppressing shim before solid-refresh's transform runs.SSR environment is hard-coded to
addHmr: false.start-plugin-core/src/vite/start-router-plugin/plugin.tsregisters twotanStackRouterCodeSplitterinstances — client withaddHmr: true, server withaddHmr: false. So nohot.acceptis ever injected into the SSR module graph, which means an SSR module change produces(ssr) page reloadregardless of what the client side does. The Vite Environment API then escalates that to[vite] program reloadon the client. For Solid this is the dominant signal — the SSR-side reload always wins over the client-side accept.
Happy to send a PR taking a stab at either:
- Adding a minimal
createSolidRefreshIgnoredRouteExportsPluginthat emits// @refresh skip(or the_$Hot$ignorepragmasolid-refreshactually honors — need to dig) for non-component route exports. - Flipping the SSR
addHmrtotrueand seeing what breaks. My intuition is that SSR HMR for routes is safe given that route modules are pure config + a component reference, but I haven't traced the full SSR refresh path yet.
Let me know which direction you'd like to take and I'll open something against the branch.
@sananes we don't want to talk to an LLM here so don't continue this
@sananes we don't want to talk to an LLM here so don't continue this
That's a fair point. Apologies. I can redact the comment if you prefer?
no worries, just be human from now on :D
what would help is starting to port the react hmr e2e test to solid and then experiment what is needed to fix things for solid
Sign in to join this conversation.
Do you have a reproduction project. It seems like HMR isn't reloading for __root but its not showing a blank page an erroring either.
Also do you know if the react version works?