perf: make the Node compile cache opt-in, persist worker caches on teardown (#10742)

Author: sheremet-va

docs/guide/improving-performance.md

@@ -91,6 +91,18 @@ Duration  8.75s (transform 4.02s, setup 629ms, import 5.52s, tests 2.52s, enviro
 Duration  5.90s (transform 842ms, setup 543ms, import 2.35s, tests 2.94s, environment 0ms, prepare 3ms)
 ```
 
+## Node Compile Cache
+
+Vitest supports Node's [on-disk compile cache](https://nodejs.org/api/cli.html#node_compile_cachedir): when the `NODE_COMPILE_CACHE` environment variable points at a directory, the V8 bytecode of Vitest's own modules and of your externalized dependencies is written to disk and reused by later runs instead of being recompiled. Vitest propagates the variable to every worker, and workers persist the modules they compiled when they shut down.
+
+```shell
+NODE_COMPILE_CACHE=node_modules/.cache/node-compile-cache vitest
+```
+
+The first run with an empty directory pays for serializing the compiled modules, so this is only worth enabling when the directory survives between runs: local runs, or CI pipelines that cache the directory. `NODE_DISABLE_COMPILE_CACHE=1` disables the cache entirely, taking precedence over `NODE_COMPILE_CACHE`.
+
+Note that Vitest automatically disables the compile cache in workers when the `v8` coverage provider is enabled — V8 serializes cached scripts without the source positions that precise coverage relies on.
+
 ## Pool
 
 By default Vitest runs tests in `pool: 'forks'`. While `'forks'` pool is better for compatibility issues ([hanging process](/guide/common-errors.html#failed-to-terminate-worker) and [segfaults](/guide/common-errors.html#segfaults-and-native-code-errors)), it may be slightly slower than `pool: 'threads'` in larger projects.

packages/vitest/src/runtime/workers/init.ts

@@ -2,6 +2,9 @@ import type { WorkerRequest, WorkerResponse } from '../../node/pools/types'
 import type { MetaEnv, WorkerSetupContext } from '../../types/worker'
 import type { FileSpecification } from '../runner/types'
 import type { VitestWorker } from './types'
+// default import: `flushCompileCache` only exists since Node 22.10, a named
+// import would fail to link on older versions
+import Module from 'node:module'
 import { serializeError } from '@vitest/utils/error'
 import { disableDefaultColors } from 'tinyrainbow'
 import { Traces } from '../../utils/traces'
@@ -241,6 +244,20 @@ export function init(worker: Options): void {
       case 'stop': {
         await runPromise
 
+        // Persist this worker's compile cache before the parent tears the
+        // worker down — forks are SIGTERM'd and never reach Node's exit-time
+        // flush, so without this the cache stays write-only for them. Runs
+        // even when teardown throws (the compiled modules are still worth
+        // persisting). A no-op when the cache is disabled or was fully loaded
+        // from disk, and cheap (~tens of ms) otherwise, so every worker can
+        // afford it.
+        const persistCompileCache = () => {
+          try {
+            Module.flushCompileCache?.()
+          }
+          catch {}
+        }
+
         try {
           const context = traces.getContextFromCarrier(message.otelCarrier)
 
@@ -256,9 +273,13 @@ export function init(worker: Options): void {
 
           await traces.finish()
 
+          persistCompileCache()
+
           send({ type: 'stopped', error, __vitest_worker_response__ })
         }
         catch (error) {
+          persistCompileCache()
+
           send({ type: 'stopped', error: serializeError(error), __vitest_worker_response__ })
         }
 

packages/vitest/vitest.mjs

@@ -1,19 +1,2 @@
 #!/usr/bin/env node
-import * as module from 'node:module'
-
-// Enable Node's on-disk compile cache before importing the CLI so both the CLI
-// graph and (via the inherited env variable) every spawned worker skip V8
-// recompilation of unchanged modules. `enableCompileCache()` only affects the
-// current process — child processes pick the cache up from NODE_COMPILE_CACHE.
-// Respects an explicit NODE_COMPILE_CACHE and NODE_DISABLE_COMPILE_CACHE; the
-// API is not available before Node 22.8.
-try {
-  const result = module.enableCompileCache?.()
-  if (result?.directory && !process.env.NODE_COMPILE_CACHE) {
-    process.env.NODE_COMPILE_CACHE = result.directory
-  }
-}
-catch {}
-
-// eslint-disable-next-line antfu/no-top-level-await -- the import must not be hoisted above `enableCompileCache`
-await import('./dist/cli.js')
+import './dist/cli.js'

pnpm-lock.yaml

@@ -0,0 +1,16 @@
+import { expect, test } from 'vitest'
+
+test('worker sees the expected compile cache environment', () => {
+  // set when the spec expects the v8 coverage provider to strip the cache
+  if (process.env.EXPECT_COVERAGE_STRIPPED) {
+    expect(process.env.NODE_COMPILE_CACHE).toBeUndefined()
+    expect(process.env.NODE_DISABLE_COMPILE_CACHE).toBe('1')
+  }
+  // gate on the discriminator between the spec's runs, not on
+  // EXPECTED_COMPILE_CACHE_DIR itself — if the spec's env stops propagating,
+  // this fails loudly (toBe(undefined)) instead of passing vacuously
+  else if (!process.env.NODE_DISABLE_COMPILE_CACHE) {
+    expect(process.env.NODE_COMPILE_CACHE).toBe(process.env.EXPECTED_COMPILE_CACHE_DIR)
+  }
+  expect(document).toBeDefined()
+})

test/e2e/fixtures/compile-cache/basic.test.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    watch: false,
+    environment: 'jsdom',
+    pool: 'forks',
+  },
+})

test/e2e/fixtures/compile-cache/vitest.config.ts

@@ -24,6 +24,7 @@
     "@vitejs/test-dep-virtual": "file:./deps/test-dep-virtual",
     "@vitest/browser-playwright": "workspace:*",
     "@vitest/browser-preview": "workspace:*",
+    "@vitest/coverage-v8": "workspace:*",
     "@vitest/mocker": "workspace:*",
     "@vitest/test-dep-optimizer-external": "file:./deps/optimizer/external",
     "@vitest/test-dep-optimizer-optimized": "file:./deps/optimizer/optimized",

test/e2e/package.json

@@ -0,0 +1,76 @@
+import { existsSync, readdirSync, rmSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { expect, test } from 'vitest'
+import { runVitestCli } from '../../test-utils'
+
+const fixture = resolve(import.meta.dirname, '../fixtures/compile-cache')
+const cacheDir = resolve(fixture, 'node_modules/.cache/compile-cache-test')
+
+function cacheEntries(): string[] {
+  return readdirSync(cacheDir, { recursive: true, encoding: 'utf-8' })
+    .filter(file => statSync(join(cacheDir, file)).isFile())
+}
+
+test('NODE_COMPILE_CACHE redirects the compile cache and the worker persists its graph', async () => {
+  rmSync(cacheDir, { recursive: true, force: true })
+
+  // the fixture test asserts that the worker sees this exact NODE_COMPILE_CACHE
+  const { exitCode } = await runVitestCli(
+    { nodeOptions: { env: {
+      NODE_COMPILE_CACHE: cacheDir,
+      EXPECTED_COMPILE_CACHE_DIR: cacheDir,
+    } } },
+    'run',
+    '--root',
+    fixture,
+  )
+
+  expect(exitCode).toBe(0)
+
+  // jsdom is only loaded inside the worker, so its modules can reach the
+  // cache only through the worker flush — the CLI graph alone is ~150 entries,
+  // the worker graph pushes it past 1000
+  expect(cacheEntries().length).toBeGreaterThan(300)
+})
+
+test('NODE_DISABLE_COMPILE_CACHE wins over NODE_COMPILE_CACHE', async () => {
+  rmSync(cacheDir, { recursive: true, force: true })
+
+  const { exitCode } = await runVitestCli(
+    { nodeOptions: { env: {
+      NODE_COMPILE_CACHE: cacheDir,
+      NODE_DISABLE_COMPILE_CACHE: '1',
+    } } },
+    'run',
+    '--root',
+    fixture,
+  )
+
+  expect(exitCode).toBe(0)
+  expect(existsSync(cacheDir)).toBe(false)
+})
+
+test('the cache is stripped from workers when v8 coverage is enabled', async () => {
+  rmSync(cacheDir, { recursive: true, force: true })
+
+  const { exitCode } = await runVitestCli(
+    { nodeOptions: { env: {
+      NODE_COMPILE_CACHE: cacheDir,
+      EXPECT_COVERAGE_STRIPPED: '1',
+    } } },
+    'run',
+    '--root',
+    fixture,
+    '--coverage.enabled',
+    '--coverage.provider=v8',
+    '--coverage.reporter=text',
+  )
+
+  expect(exitCode).toBe(0)
+
+  // the CLI process itself still persists its own graph (Node enabled its
+  // cache from the env var at startup, before coverage is known), but the
+  // worker's jsdom graph must not reach the cache
+  const entries = existsSync(cacheDir) ? cacheEntries() : []
+  expect(entries.length).toBeLessThan(300)
+})