Skip to content
Source
Sign inSign up
TanStack/router

Vite HMR blank page when editing `__root.tsx` (Solid SSR) #6331

Send to my agent
Openyanghuidong(GitHub profile, opens in a new tab) opened this issue 11 comments

Which 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

  1. Create TanStack Start (Solid) app
  2. pnpm dev
  3. Edit __root.tsx (e.g. change some text)
  4. Observe: Blank page, console shows template2 is not a function
  5. 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

  1. 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?

    pnpx create-start-app --framework solid
  2. @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
    ...
    Image Image Image
  3. 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!

  4. schiller-manuel(GitHub profile, opens in a new tab) added labelspackage: solid-router

  5. schiller-manuel(GitHub profile, opens in a new tab) added labelspackage: solid-start

  6. Ok I think I have a fix. Can you add this at the top of __root.tsx?

    // @refresh reload

    Ii 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

  7. 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.tsx

    But ideally, Solid's behavior when working with Vite HMR can catch up with React.

  8. 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 reload

    Traced 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.ts

    switch (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 a hot.accept handler into transformed route files, so every route change bubbles to the root and Vite falls back to full-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 a solid-refresh analog.

    Happy to help scope or prototype if useful. Reproducing on @tanstack/solid-start@1.167.x / @tanstack/solid-router@1.168.x / Vite 8.

  9. 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

  10. 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?

    b86b061

    And another fix for route matching here:

    a1c52f1

    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, but b86b061 was reverted on it (b0024d6). To test the intended fix I had to checkout b86b061 and cherry-pick the regex fix from a1c52f1 on top, then pnpm pack the 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.js includes case "solid": returning createRefreshRouteComponentsPlugin() + createStableHmrSplitRouteComponentsPlugin().
    • curl on a route file at dev time shows the import.meta.hot.accept(...) block from vite-adapter.ts correctly appended after createFileRoute(...). So the inject path is wired and runs for Solid.

    But the original symptom still reproduces. Editing any file under src/routes/**/*.tsx still triggers:

    [vite] (client) page reload src/routes/<file>.tsx
    [vite] (ssr)    page reload src/routes/<file>.tsx
    [vite] program reload

    I think there are two remaining gaps:

    1. No Solid analog of react-refresh-ignored-route-exports. The React case returns three plugins; the new Solid case returns only two. Without an "ignored route exports" plugin, solid-refresh (via vite-plugin-solid) sees the non-component Route = createFileRoute(...) export, treats the module as non-refreshable, and invalidates it — which is what produces the page reload on the client side even though our import.meta.hot.accept is sitting right there. You called this out in your earlier comment ("would need a solid-refresh analog"); the fix as merged does not address it. solid-refresh doesn't expose the same explicit register/ignore API as react-refresh, but I think it can be approximated by wrapping the route module in a // @refresh skip / // @refresh reload annotation per route file, or by directly emitting a hot.invalidate()-suppressing shim before solid-refresh's transform runs.

    2. SSR environment is hard-coded to addHmr: false. start-plugin-core/src/vite/start-router-plugin/plugin.ts registers two tanStackRouterCodeSplitter instances — client with addHmr: true, server with addHmr: false. So no hot.accept is ever injected into the SSR module graph, which means an SSR module change produces (ssr) page reload regardless of what the client side does. The Vite Environment API then escalates that to [vite] program reload on 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 createSolidRefreshIgnoredRouteExportsPlugin that emits // @refresh skip (or the _$Hot$ignore pragma solid-refresh actually honors — need to dig) for non-component route exports.
    • Flipping the SSR addHmr to true and 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.

  11. @sananes we don't want to talk to an LLM here so don't continue this

  12. @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?

  13. 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.