@cloudflare/vite-plugin: editing index.html restarts the dev server and races the page reload

[kunalbhagawati]

Which Cloudflare product(s) does this pertain to?

@cloudflare/vite-plugin

What version(s) of the tool(s) are you using?

@cloudflare/vite-plugin@1.54.0 (also present in the published 1.54.4), vite@8.2.2, wrangler@4.126.0

What version of Node are you using?

24

Describe the Bug

Editing the client's index.html restarts the entire Vite dev server, while Vite simultaneously sends the browser a page reload. The reload lands on a server that is still restarting, so the tab hangs instead of showing the change. A plain vite dev server (plugin removed) does a clean page reload index.html for the same edit.

The cause looks like additional-modules.ts: .html is one of the Text module rules, and the hot-update hook restarts the server for any path in additionalModulePaths:

const moduleRules = [
  { type: "CompiledWasm", pattern: /\.wasm(\?module)?$/ },
  { type: "Data",         pattern: /\.bin$/ },
  { type: "Text",         pattern: /\.(txt|html|sql)$/ },
];

hotUpdate(options) {
  if (additionalModulePaths.has(options.file)) {
    options.server.restart();
    return [];
  }
}

A restart is correct for a .html / .txt / .sql file the Worker imports, since it is baked into the Worker bundle at startup. The client's own HTML entry ends up in the same set, and for it a restart is both unnecessary and actively harmful, because it races Vite's own page reload.

Server log with the plugin enabled, after touch index.html:

@CLOUDFLARE:VITE-PLUGIN 72290: From server.restart(): Restarting server...
[vite] (client) page reload index.html
[vite] server restarted.

Same edit with the plugin removed:

[vite] (client) page reload index.html

A Worker-imported .html (import template from './authorize-page.html?raw') produces the identical restart signature, which is the expected behaviour for that file.

Please provide a link to a minimal reproduction

No response

Please provide any relevant error logs

Repro on any Worker + SPA app created with the plugin:

1. vite dev
2. Open the app in a browser.
3. Edit index.html (a whitespace change is enough).
4. The dev server restarts and the browser's reload hangs until the server is back.

Locally patching the hook to skip the Vite root's index.html fixes it and leaves Worker-imported text modules restarting as before.

[workers-devprod]

Automated triage

Issue assessment

• Actionability: ✅ Actionable.
• Type: Bug (high confidence).
• Reproduction: Automatic attempt requested.
• Labels:
  • package:vite-plugin (high)

Actionability and missing information

Editing client index.html triggers a full Vite dev server restart that races the plugin's page reload, hanging the tab; versions, environment, repro steps, logs with and without the plugin, expected vs actual behavior, and a suspected code path are provided; only a minimal repro link is missing.

Reproduction reason: The report describes a current dev-server behavior defect with concrete steps, versions, and comparison logs, so reproduction can be attempted from the stated evidence.

Missing information:

• minimal reproduction

Reproduction

• Result: ✅ Reproduced.
• Summary: Reproduced: editing index.html with the Cloudflare Vite plugin 1.54.0 (vite 8.2.2) prints both "page reload index.html" and "[vite] server restarted."; requests in the restart window hang 400-670ms or fail (UND_ERR_SOCKET). Baseline without plugin: page reload only, no restart.

Evidence and attempted steps

Steps attempted:

1. Installed the minimal Worker + SPA fixture (index.html at Vite root, wrangler.toml, src/worker.js, vite.config.js with the cloudflare() plugin) using the exact versions reported in the issue
   • Command: pnpm install (in project/ with pinned cloudflare/vite-plugin 1.54.0, vite 8.2.2, wrangler 4.126.0)
2. Run 1 (plugin enabled): started the Vite dev server, fetched /, edited index.html (heading v0 to v1), probed the server, and inspected the dev-server log
   • Command: node reproduce.mjs
3. Run 2 (single baseline, plugin removed): identical fixture and edit with a vite.config that omits the Cloudflare plugin
   • Command: node reproduce.mjs --baseline
4. Run 3 (plugin enabled): repeated with 20ms-interval probes to capture requests inside the restart window
   • Command: node reproduce.mjs

Expected behavior: Editing the client's index.html during vite dev with the Cloudflare Vite plugin (npm cloudflare/vite-plugin 1.54.0) should behave like plain Vite: emit only a page reload for index.html, with no dev-server restart and no disruption to in-flight requests.

Observed behavior: With the Cloudflare Vite plugin 1.54.0 (vite 8.2.2, wrangler 4.126.0): editing index.html printed BOTH "[vite] (client) page reload index.html" AND "[vite] server restarted." (Vite prints the latter only when server.restart() is invoked) — restart observed: true. Requests fired in the ~775ms restart window hung 400-670ms and one failed with UND_ERR_SOCKET (connection torn down mid-restart), i.e. the browser's automatic reload races the restarting server. Baseline with the identical fixture minus the plugin: only "[vite] (client) page reload index.html", restart observed: false. Matches the issue exactly.

Artifact: Download reproduction archive (Cloudflare Access required).

Treat archive contents as untrusted. Inspect them before running anything.

---

This summary was generated by an LLM and may contain errors. Please verify its findings.

[kunalbhagawati]

Follow-up: I tried to reproduce this inside the repo before proposing a fix, and the playgrounds do not reproduce it - so the trigger is narrower than my original report implies.

What I ran, on main (8bbcb9f), with @cloudflare/vite-plugin and its deps built from source:

1. packages/vite-plugin-cloudflare/playground/spa-with-api, vite dev, touch index.html
   → [vite] (client) page reload index.html, no restart.
2. Same playground with the Worker additionally importing an .html module (import workerPage from "./worker-page.html", served from /api/worker-page, so the path is definitely in additionalModulePaths), touch index.html
   → still page reload index.html, no restart.

So .html being a Text module rule is not on its own enough; a plain SPA + Worker does not hit it.

What I can still say with confidence from the downstream app where it does happen (Vite 8.2.2, plugin 1.54.0):

• Patching only the hotUpdate hook in additional-modules.ts to skip the Vite root's index.html fixes it, and a Worker-imported .html still restarts as before. That is what the local pnpm patch does, and it is verified both ways on a fresh dev server.
• Because that patch is sufficient, the restart in that app is definitely flowing through additionalModulePaths.has(options.file) - i.e. the client's index.html really is in that set there.
• With the plugin removed entirely (E2E_NO_WORKER=1), the same edit is a clean page reload.

I have not yet isolated what puts index.html into additionalModulePaths in that app but not in the playground. I did not open a PR because I could not reproduce the failure here, and a fix I cannot exercise against a failing case is not one I want to put in front of you. Happy to keep narrowing it down, or to run any instrumented build you would like against the app that reproduces it.

[vahidshaik1901]

I have not yet isolated what puts index.html into additionalModulePaths in that app but not in the playground.

It reproduces in spa-with-api as soon as the Worker imports the Vite root's index.html itself. Your test 2 imported a different .html (worker-page.html), which is why it stayed clean — the set only ever contains paths the worker environment actually resolved, so a sibling .html does not put the client entry in it.

A/B on main (8bbcb9f), plugin and deps built from source, packages/vite-plugin-cloudflare/playground/spa-with-api:

With one line added to api/index.ts:

import indexHtml from "../index.html";
// ...served from /api/index-html so the import is not tree-shaken

touch index.html:

[vite] (client) page reload index.html
[vite] server restarted.

Without that import, same file, same edit:

[vite] (client) page reload index.html

So both halves of the race you described — the reload and the restart — appear together exactly when the client entry is in the worker's module graph, and the restart disappears when it is not.

Why this is easy to hit in a real app and not in a playground: resolveId is filtered on /\.(txt|html|sql)$/ and gated to worker environments, so anything in the worker graph that resolves the root HTML lands in additionalModulePaths — a Worker that reads the HTML template to do its own shell rendering, or a framework plugin whose SSR entry pulls in the client entry, gets there without anyone writing an obvious import "./index.html". Worth checking your app's worker graph for a path that ends up at the Vite root index.html.

That also lines up with your finding that patching only the hotUpdate hook to skip the Vite root's index.html fixes it while a Worker-imported .html still restarts as before — which now has a failing case in-repo to exercise it against.

I have not opened a PR; this is yours, and you have the downstream case to validate against. Reproduction steps above if you want it as a playground test.