@unseal-ai/vite-plugin-hmr-gate

A Vite development-server plugin that buffers file watcher events until an external process releases them. It prevents HMR from reacting to incomplete multi-file writes, then refreshes the preview once the batch is ready.

Install

npm install -D @unseal-ai/vite-plugin-hmr-gate

Usage

Enable the gate with HMR_GATE=1 and add the plugin to vite.config.ts.

import { defineConfig } from "vite";
import { hmrGate } from "@unseal-ai/vite-plugin-hmr-gate";

export default defineConfig({
  plugins: [
    hmrGate({
      // Optional path fragments to let through without buffering.
      passthrough: ["/.generated/"],
    }),
  ],
});

When HMR_GATE is unset, the plugin is a no-op and Vite uses its normal HMR behavior.

Endpoints

• POST /__hmr_flush releases every buffered event, invalidates Vite's module graph, and normally replays watcher events while suppressing granular client HMR. It waits for non-client environments (including the SSR module runner) to settle, drains watcher events generated by plugins, and then sends one full reload. If the batch changes package.json or a package-manager lockfile, it instead discards HMR replay and forces one Vite dependency re-optimization restart. The response is { flushed, count } when the connection survives; a restart may close the flush connection.
• GET /__hmr_status returns the buffered events as { gated, pending, count }.

Behavior

• Buffers change, add, and unlink events.
• Bypasses node_modules/.vite by default. Use passthrough to add paths.
• Keeps each event type once per file until flush.
• Drops a change when the file returns to its last flushed content.
• Never sends a granular client update from a flush before its full reload.
• Treats dependency-graph changes as a cold-restart boundary so one document can never mix old and newly optimized React runtimes.
• Preserves normal granular HMR for file changes outside a gated flush.
• Restores Vite's original watcher emitter when the dev server closes.