Postmortem: A Vite 6.0 HMR Bug Caused Our Development Environment to Crash 10+ Times per Day

// reproduction.js
// Minimal reproduction of Vite 6.0 HMR memory leak causing dev server crashes
// Requires: vite@6.0.3, node@20.11.0+, a test React component
import { createServer } from 'vite';
import { execSync } from 'child_process';
import { writeFileSync, unlinkSync } from 'fs';
import { resolve } from 'path';

// Configuration
const PORT = 3000;
const HMR_UPDATE_INTERVAL_MS = 2000; // Trigger HMR update every 2s
const MAX_UPDATES = 15; // Number of updates to send before checking memory
const TEST_COMPONENT_PATH = resolve('./src/TestComponent.jsx');

// 1. Set up test project structure
function setupTestProject() {
  try {
    execSync('mkdir -p src', { stdio: 'inherit' });
    // Create a simple React component to trigger HMR updates on
    writeFileSync(
      TEST_COMPONENT_PATH,
      `export default function TestComponent() {
  return Version 1;
}`
    );
    // Create minimal vite config
    writeFileSync(
      './vite.config.js',
      `import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: { port: ${PORT} }
});`
    );
    console.log('✅ Test project setup complete');
  } catch (err) {
    console.error('❌ Failed to setup test project:', err.message);
    process.exit(1);
  }
}

// 2. Start Vite dev server and track memory
async function startServerAndTrackMemory() {
  let updateCount = 0;
  let server;

  try {
    server = await createServer({
      root: process.cwd(),
      logLevel: 'error' // Suppress noise
    });
    await server.listen();
    console.log(`✅ Vite dev server running on http://localhost:${PORT}`);

    // Track memory usage every 2 seconds
    const memoryInterval = setInterval(() => {
      const memUsage = process.memoryUsage();
      const heapUsedMB = (memUsage.heapUsed / 1024 / 1024).toFixed(2);
      const heapTotalMB = (memUsage.heapTotal / 1024 / 1024).toFixed(2);
      console.log(`[Update ${updateCount}] Heap: ${heapUsedMB}MB used / ${heapTotalMB}MB total`);
    }, HMR_UPDATE_INTERVAL_MS);

    // Trigger HMR updates by modifying the test component
    const updateInterval = setInterval(() => {
      if (updateCount >= MAX_UPDATES) {
        clearInterval(updateInterval);
        clearInterval(memoryInterval);
        return;
      }
      updateCount++;
      const newContent = `export default function TestComponent() {
  return Version ${updateCount};
}`;
      try {
        writeFileSync(TEST_COMPONENT_PATH, newContent);
        // Force Vite to detect the file change (in case chokidar is slow)
        server.watcher.emit('change', TEST_COMPONENT_PATH);
      } catch (err) {
        console.error(`❌ Failed to update component on iteration ${updateCount}:`, err.message);
      }
    }, HMR_UPDATE_INTERVAL_MS);

    // Wait for all updates to complete, then teardown
    await new Promise(resolve => setTimeout(resolve, HMR_UPDATE_INTERVAL_MS * (MAX_UPDATES + 2)));
  } catch (err) {
    console.error('❌ Dev server error:', err.message);
  } finally {
    if (server) await server.close();
    // Cleanup test files
    try {
      unlinkSync(TEST_COMPONENT_PATH);
      unlinkSync('./vite.config.js');
      execSync('rm -rf src');
      console.log('✅ Cleanup complete');
    } catch (err) {
      console.warn('⚠️ Cleanup warning:', err.message);
    }
  }
}

// Run reproduction
setupTestProject();
startServerAndTrackMemory();

// vite-plugin-hmr-memory-fix.js
// Interim patch for Vite 6.0.x HMR memory leak
// Fixes unclosed async iterator references in HMR dependency graph traversal
import { resolve } from 'path';
import { readFileSync, writeFileSync, existsSync } from 'fs';

const PLUGIN_NAME = 'vite-plugin-hmr-memory-fix';
// Matches the Vite internal HMR handler path introduced in 6.0.0
const HMR_HANDLER_PATH = resolve(
  process.cwd(),
  'node_modules/vite/dist/node/chunks/dep-abc123.js' // Adjust hash to your Vite build
);

export function hmrMemoryFixPlugin() {
  let isPatched = false;

  return {
    name: PLUGIN_NAME,
    apply: 'serve', // Only run in dev mode
    async configResolved(config) {
      // Skip if not Vite 6.0.x
      const viteVersion = config.viteVersion || 'unknown';
      if (!viteVersion.startsWith('6.0.')) {
        console.warn(`[${PLUGIN_NAME}] Skipping patch: Vite version ${viteVersion} not affected`);
        return;
      }

      try {
        if (!existsSync(HMR_HANDLER_PATH)) {
          console.error(`[${PLUGIN_NAME}] Could not find HMR handler at ${HMR_HANDLER_PATH}`);
          console.error(`[${PLUGIN_NAME}] Please check your Vite installation path`);
          return;
        }

        let handlerContent = readFileSync(HMR_HANDLER_PATH, 'utf-8');
        const originalSnapshot = handlerContent;

        // 1. Patch: Add try block after for await loop start
        const FOR_AWAIT_REGEX = /(for await \(const (\w+) of (\w+)\) \{)/;
        if (!FOR_AWAIT_REGEX.test(handlerContent)) {
          console.warn(`[${PLUGIN_NAME}] No for await loop found in HMR handler, skipping patch`);
          return;
        }
        handlerContent = handlerContent.replace(
          FOR_AWAIT_REGEX,
          '$1\n  try {'
        );

        // 2. Patch: Add finally block to close iterator before loop end
        const LOOP_CLOSE_REGEX = /(\n  \}) \/\/ end for await/g;
        handlerContent = handlerContent.replace(
          LOOP_CLOSE_REGEX,
          '\n  } finally {\n    // Close async iterator to prevent memory leak\n    if ($3 && typeof $3.return === \"function\") $3.return();\n  }\n$1'
        );

        // 3. Verify patch was applied
        if (handlerContent === originalSnapshot) {
          console.warn(`[${PLUGIN_NAME}] No changes made to HMR handler, patch may be unnecessary`);
          return;
        }

        // 4. Write patched file (with backup)
        const backupPath = `${HMR_HANDLER_PATH}.backup`;
        writeFileSync(backupPath, originalSnapshot);
        writeFileSync(HMR_HANDLER_PATH, handlerContent);
        isPatched = true;
        console.log(`[${PLUGIN_NAME}] ✅ Successfully patched HMR handler. Backup saved to ${backupPath}`);
      } catch (err) {
        console.error(`[${PLUGIN_NAME}] ❌ Failed to apply patch:`, err.message);
        console.error(`[${PLUGIN_NAME}] Please apply the patch manually from https://github.com/vitejs/vite/pull/12345`);
      }
    },
    async buildStart() {
      if (isPatched) {
        console.log(`[${PLUGIN_NAME}] Patched HMR handler active. Monitor memory usage with --debug hmr`);
      }
    }
  };
}

// Usage in vite.config.js:
// import { hmrMemoryFixPlugin } from './vite-plugin-hmr-memory-fix';
// export default defineConfig({
//   plugins: [hmrMemoryFixPlugin(), react()],
// });

// benchmark-hmr.js
// Benchmark HMR memory usage and update time across Vite versions
// Usage: node benchmark-hmr.js [vite-version] (e.g., node benchmark-hmr.js 5.4.2)
import { execSync } from 'child_process';
import { writeFileSync, unlinkSync, existsSync } from 'fs';
import { resolve } from 'path';
import { performance } from 'perf_hooks';

const BENCHMARK_ROUNDS = 10;
const COMPONENT_COUNT = 140; // Match our monorepo's component count
const HMR_UPDATE_DELAY_MS = 1000;

async function runBenchmark(viteVersion) {
  console.log(`\n📊 Starting HMR benchmark for Vite ${viteVersion}`);
  console.log(`📊 Rounds: ${BENCHMARK_ROUNDS}, Components: ${COMPONENT_COUNT}`);

  // 1. Install target Vite version
  try {
    console.log(`📦 Installing vite@${viteVersion}...`);
    execSync(`npm install vite@${viteVersion} --save-dev --silent`, { stdio: 'inherit' });
  } catch (err) {
    console.error(`❌ Failed to install Vite ${viteVersion}:`, err.message);
    return null;
  }

  // 2. Generate test components to match monorepo size
  const testComponents = [];
  try {
    execSync('mkdir -p src/benchmark-components', { stdio: 'inherit' });
    for (let i = 0; i < COMPONENT_COUNT; i++) {
      const componentPath = resolve(`./src/benchmark-components/Component${i}.jsx`);
      writeFileSync(
        componentPath,
        `export default function Component${i}() {
  return Benchmark Component ${i};
}`
      );
      testComponents.push(componentPath);
    }
    console.log(`✅ Generated ${COMPONENT_COUNT} test components`);
  } catch (err) {
    console.error('❌ Failed to generate test components:', err.message);
    return null;
  }

  // 3. Run HMR updates and collect metrics
  const metrics = {
    hmrUpdateTimes: [],
    memorySnapshots: [],
    crashCount: 0
  };

  for (let round = 0; round < BENCHMARK_ROUNDS; round++) {
    console.log(`\n🔄 Round ${round + 1}/${BENCHMARK_ROUNDS}`);
    let server;
    try {
      // Start Vite dev server
      const { createServer } = await import('vite');
      server = await createServer({
        root: process.cwd(),
        logLevel: 'error'
      });
      await server.listen();

      // Collect initial memory
      const initialMemory = process.memoryUsage().heapUsed;
      metrics.memorySnapshots.push({ round, initial: initialMemory });

      // Trigger HMR update for a random component
      const randomComponent = testComponents[Math.floor(Math.random() * COMPONENT_COUNT)];
      const startTime = performance.now();
      writeFileSync(
        randomComponent,
        `export default function ${randomComponent.split('/').pop().replace('.jsx', '')}() {
  return Updated Benchmark Component;
}`
      );
      // Wait for HMR to process
      await new Promise(resolve => setTimeout(resolve, HMR_UPDATE_DELAY_MS));
      const updateTime = performance.now() - startTime;
      metrics.hmrUpdateTimes.push(updateTime);

      // Collect post-update memory
      const postUpdateMemory = process.memoryUsage().heapUsed;
      metrics.memorySnapshots.push({ round, postUpdate: postUpdateMemory });

      console.log(`✅ HMR update took ${updateTime.toFixed(2)}ms`);
      console.log(`✅ Memory delta: ${((postUpdateMemory - initialMemory) / 1024 / 1024).toFixed(2)}MB`);
    } catch (err) {
      metrics.crashCount++;
      console.error(`❌ Round ${round + 1} crashed:`, err.message);
    } finally {
      if (server) await server.close();
    }
  }

  // 4. Calculate summary statistics
  const avgUpdateTime = metrics.hmrUpdateTimes.reduce((a, b) => a + b, 0) / metrics.hmrUpdateTimes.length;
  const avgMemoryDelta = metrics.memorySnapshots.reduce((acc, curr) => {
    if (curr.postUpdate && curr.initial) {
      acc += curr.postUpdate - curr.initial;
    }
    return acc;
  }, 0) / BENCHMARK_ROUNDS;

  const summary = {
    viteVersion,
    avgHmrUpdateTimeMs: avgUpdateTime.toFixed(2),
    avgMemoryDeltaPerUpdateMB: (avgMemoryDelta / 1024 / 1024).toFixed(2),
    crashCount: metrics.crashCount,
    roundsCompleted: BENCHMARK_ROUNDS - metrics.crashCount
  };

  // Cleanup
  try {
    testComponents.forEach(c => unlinkSync(c));
    execSync('rm -rf src/benchmark-components');
    execSync('npm uninstall vite --silent');
  } catch (err) {
    console.warn('⚠️ Cleanup warning:', err.message);
  }

  return summary;
}

// Run benchmarks for affected versions
const versionsToTest = process.argv[2] ? [process.argv[2]] : ['5.4.2', '6.0.3', '6.1.0-rc.1'];
const results = [];

for (const version of versionsToTest) {
  const result = await runBenchmark(version);
  if (result) results.push(result);
}

console.log('\n📊 Benchmark Results:');
console.table(results);

// vite-plugin-hmr-metrics.js
import { register, Counter, Histogram, Gauge } from 'prom-client';

const hmrUpdatesTotal = new Counter({
  name: 'vite_hmr_updates_total',
  help: 'Total number of HMR updates',
  labelNames: ['status'] // success, failure
});

const hmrUpdateDuration = new Histogram({
  name: 'vite_hmr_update_duration_ms',
  help: 'HMR update duration in milliseconds',
  buckets: [50, 100, 200, 500, 1000, 2000]
});

const hmrHeapUsage = new Gauge({
  name: 'vite_hmr_heap_usage_bytes',
  help: 'Current Vite dev server heap usage in bytes'
});

export function hmrMetricsPlugin() {
  return {
    name: 'vite-plugin-hmr-metrics',
    apply: 'serve',
    configureServer(server) {
      // Expose /metrics endpoint
      server.middlewares.use('/metrics', (req, res) => {
        if (req.url === '/metrics') {
          res.setHeader('Content-Type', register.contentType);
          res.end(register.metrics());
        }
      });

      // Track HMR update start
      let updateStart;
      server.hmr.on('update-start', () => {
        updateStart = Date.now();
      });

      // Track HMR update end
      server.hmr.on('update-end', (payload) => {
        const duration = Date.now() - updateStart;
        hmrUpdateDuration.observe(duration);
        hmrUpdatesTotal.inc({ status: payload.errors ? 'failure' : 'success' });
        hmrHeapUsage.set(process.memoryUsage().heapUsed);
      });
    }
  };
}

// hmr.regression.test.ts
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { createServer } from 'vite';
import { writeFileSync, unlinkSync } from 'fs';
import { resolve } from 'path';
import { performance } from 'perf_hooks';

describe('Vite HMR Regression Tests', () => {
  let server;
  const TEST_COMPONENT = resolve('./src/TestHmrComponent.jsx');

  beforeAll(async () => {
    // Start Vite dev server
    server = await createServer({
      root: process.cwd(),
      logLevel: 'error'
    });
    await server.listen();
    // Create initial test component
    writeFileSync(TEST_COMPONENT, `export default function TestHmrComponent() { return V1; }`);
  });

  afterAll(async () => {
    if (server) await server.close();
    unlinkSync(TEST_COMPONENT);
  });

  it('should deliver HMR update within 500ms', async () => {
    const startTime = performance.now();
    writeFileSync(TEST_COMPONENT, `export default function TestHmrComponent() { return V2; }`);
    server.watcher.emit('change', TEST_COMPONENT);
    // Wait for HMR to process
    await new Promise(resolve => setTimeout(resolve, 1000));
    const duration = performance.now() - startTime;
    expect(duration).toBeLessThan(500);
  });

  it('should not leak more than 1MB of memory per HMR update', async () => {
    const initialHeap = process.memoryUsage().heapUsed;
    for (let i = 0; i < 5; i++) {
      writeFileSync(TEST_COMPONENT, `export default function TestHmrComponent() { return V${i + 3}; }`);
      server.watcher.emit('change', TEST_COMPONENT);
      await new Promise(resolve => setTimeout(resolve, 500));
    }
    const finalHeap = process.memoryUsage().heapUsed;
    const deltaMB = (finalHeap - initialHeap) / 1024 / 1024;
    expect(deltaMB).toBeLessThan(5); // 5MB max for 5 updates
  });
});

# .husky/pre-commit
#!/bin/sh
. \"$(dirname \"$0\")/_/husky.sh\"

# Check Vite version
APPROVED_VERSIONS=(\"5.4.2\" \"6.0.4\" \"6.1.0\")
CURRENT_VERSION=$(node -e \"console.log(require('./node_modules/vite/package.json').version)\")

if [[ ! \" ${APPROVED_VERSIONS[@]} \" =~ \" ${CURRENT_VERSION} \" ]]; then
  echo \"❌ Error: Vite version ${CURRENT_VERSION} is not approved.\"
  echo \"✅ Approved versions: ${APPROVED_VERSIONS[*]}\"
  exit 1
fi

# Run HMR benchmark for new versions
if git diff --cached --name-only | grep -q \"package.json\"; then
  echo \"📊 Running HMR benchmark for Vite ${CURRENT_VERSION}...\"
  node benchmark-hmr.js ${CURRENT_VERSION}
  if [ $? -ne 0 ]; then
    echo \"❌ HMR benchmark failed. Revert Vite version change.\"
    exit 1
  fi
fi