Repository navigation
2.0.0-rc.3 | Updates in Document.jsx won't HRM update #3151
Description
Describe the bug
Might seem as a silly issue, but any updates on Document.jsx won't hot reload the module. I've added some Tailwind classes on and they only show up in my running app when I manually refresh. The same goes for adding/removing DOM elements, such as an
inside the .
Your Example Website or App
solid 2.0 rc-3
Steps to Reproduce the Bug or Issue
Install solid 2.0 rc-3 (or 4) and try and edit Document.jsx:
<html
lang="en"
class="bg-slate-900 overscroll-x-none overflow-x-hidden sm:overscroll-contain scroll-smooth">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg?v=2" />
<link rel="icon" href="/favicon.ico?v=2" />
<title>Solid App</title>
<HydrationScript />
</head>
<body class="h-dvh isolate">
<h1>Hello Solid</h1>
{props.children}
</body>
</html>Expected behavior
I expect the HMR to kick in on saving Document.jsx.
Screenshots or Videos
No response
Platform
- OS: MacOS 26.5
- Browser: Safari
- Version: 26.5
Additional context
No response
Activity
ryansolid commentedon Aug 31, 2026
Thanks for the report. This is very likely @solidjs/vite-plugin territory rather than core: the document shell (
<html>/<head>, HydrationScript) is server-rendered and can't hot-swap like a component, so the expected behavior on a Document edit is a triggered full reload — and it sounds like not even that is happening. To pin it down, could you share which template you started from, your@solidjs/vite-pluginversion, and whether editing a regular route component does HMR correctly in the same app? We're tracking it for the plugin either way.ryansolid commentedon Aug 31, 2026
Triage: not silly at all, and reproducible by inspection. A module rendering the document shell (
<html>/<head>/<body>) can never hot-swap — the markup it produces is the server-rendered scaffolding the client already claimed at hydration, and there is no boundary to re-render under (replacingdocument.documentElementlive would tear down the whole app anyway). Today solid-refresh wraps or accepts the module like any other component, so the update is absorbed silently and nothing visibly changes — the worst of both worlds.The correct behavior is for the transform to recognize document-shell modules and decline HMR for them (
import.meta.hot.decline()), which makes Vite fall back to a full page reload on save — your Tailwind classes on<html>would then show up immediately, at the cost of a reload, which is the honest cost. The fix belongs in@solidjs/vite-plugin/ solid-refresh rather than the core runtime, so it ships on the plugin's release cadence rather than with core rc.5. Leaving this open until it lands there.ryansolid commentedon Aug 31, 2026
Fixed in solidjs/solid-vite-plugin#336. The mechanism turned out to be two-sided, both in the vite plugin's dev serving:
document, so yourDocument.jsxis a real client module — the HMR transform wrapped it like any component and the update was accepted and silently absorbed (no swap can re-claimdocument.documentElement). The plugin now declines HMR for the resolved document module specifically, so saving it triggers a full page reload — your Tailwind classes on<html>show up immediately at the honest cost of a reload.Ships with the next
@solidjs/vite-pluginrelease; no core change needed.karimmaassen commentedon Sep 1, 2026
That's a swift update indeed!
Makes sense.
fix(compiler): decline document-shell modules in refresh pass so edit…
ryansolid commentedon Sep 1, 2026
Fixed in 4da3fb4 on next — the compiler's refresh pass now detects document-shell modules (intrinsic html/head/body) and takes the @refresh reload path (a decline block), so editing Document.jsx triggers a full reload that fetches a fresh server render. A document shell can't hot-swap: its elements compile with no client template (only recoverable from the hydration walk) and its static markup exists only in the server HTML. Ships in the next RC.