feat(experimental): option to disable the module runner

docs/config/experimental.md

@@ -183,3 +183,98 @@ Note that if the file path is too long, Vitest will truncate it at the start unt
 ::: info
 [Vitest UI](/guide/ui#import-breakdown) shows a breakdown of imports automatically if at least one file took longer than 500 milliseconds to load. You can manually set this option to `false` to disable this.
 :::
+
+## experimental.viteModuleRunner <Version type="experimental">4.0.16</Version> {#experimental-vitemodulerunner}
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Controls whether Vitest uses Vite's [module runner](https://vite.dev/guide/api-environment-runtimes#modulerunner) to run the code or fallback to the native `import`.
+
+If this option is defined in the root config, all [projects](/guide/projects) will inherit it automatically.
+
+We recommend disabling the module runner if you are running tests in the same environment as your code (server backend or simple scripts, for example). However, we still recommend running `jsdom`/`happy-dom` tests with the module runner or in [the browser](/guide/browser/) as it doesn't require any additional configuration.
+
+Disabling this flag will disable _all_ file transforms:
+
+- test files and your source code are not processed by Vite
+- your global setup files are not processed
+- your custom runner/pool/environment files are not processed
+- your config file is still processed by Vite's config resolution mechanism (this happens before Vitest knows the flag)
+
+::: warning
+At the moment, Vitest still requires Vite for certain functionality like the module graph or watch mode.
+:::
+
+### Module Runner
+
+By default, Vitest runs tests in a very permissive module runner sandbox powered by Vite's [Environment API](https://vite.dev/guide/api-environment.html#environment-api). Every file is categorized as either an "inline" module or an "external" module.
+
+Module runner runs all "inline" modules. It provides `import.meta.env`, `require`, `__dirname`, `__filename`, static `import`, and has its own module resolution mechanism. This makes it very easy to run code when you don't want to configure the environment and just need to test that the bare JavaScript logic you wrote works as intended.
+
+All "external" modules run in native mode, meaning they are executed outside of the module runner sandbox. If you are running tests in Node.js, these files are imported with the native `import` keyword and processed by Node.js directly.
+
+While running JSDOM/happy-dom tests in a permissive fake environment might be justified, running Node.js tests in a non-Node.js environment is counter-productive as it can hide and silence potential errors you may encounter in production, especially if your code doesn't require any additional transformations provided by Vite plugins.
+
+### Limitations
+
+Some Vitest features rely on files being transformed. Vitest uses [Node.js Loaders API](https://nodejs.org/api/module.html#customization-hooks) to transform certain files to support these features:
+
+- [`import.meta.vitest`](/guide/in-source)
+- partial [`vi.mock`](/api/vi#vi-mock) support
+
+This could affect performance because Vitest needs to read the file and process it. If you do not use these features, you can disable them by setting `experimental.nodeLoader` to `false`.
+
+Some features will not work due to the nature of `viteModuleRunner`, including:
+
+- no `import.meta.env`: `import.meta.env` is a Vite feature, use `process.env` instead
+- no `plugins`: plugins are not applied because there is no transformation phase
+- no `alias`: aliases are not applied because there is no transformation phase
+
+### TypeScript
+
+If you are using Node.js 22.18/23.6 or higher, then TypeScript will be [transformed natively](https://nodejs.org/en/learn/typescript/run-natively) by Node.js.
+
+::: warning TypeScript with Node.js 22.6-22.18
+If you are using Node.js version between 22.6 and 22.18, you can also enable native TypeScript support via `--experimental-strip-types` flag:
+
+```shell
+NODE_OPTIONS="--experimental-strip-types" vitest
+```
+
+Note that Node.js will print an experimental warning for every test file; you can silence the warning by providing `--no-warnings` flag:
+
+```shell
+NODE_OPTIONS="--experimental-strip-types --no-warnings" vitest
+```
+:::
+
+If you are using TypeScript and Node.js version lower than 22.6, then you will need to either:
+
+- build your test files and source code and run those files directly
+- import a [custom loader](https://nodejs.org/api/module.html#customization-hooks) via `execArgv` flag
+
+```ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    // TODO: validate
+    execArgv: ['--require=tsx/esm'],
+    experimental: {
+      viteModuleRunner: false,
+    },
+  },
+})
+```
+
+If you are running tests in Deno, TypeScript files are processed by the runtime without any additional configurations.
+
+## experimental.nodeLoader <Version type="experimental">4.0.16</Version> {#experimental-nodeloader}
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+If module runner is disabled, Vitest uses a module loader to transform files to support `import.meta.vitest` and `vi.mock`.
+
+If you don't use these features, you can disable this.

packages/vitest/package.json

@@ -26,7 +26,8 @@
     "#module-evaluator": {
       "types": "./dist/module-evaluator.d.ts",
       "default": "./dist/module-evaluator.js"
-    }
+    },
+    "#test-loader": "./dist/nodejs-worker-loader.js"
   },
   "exports": {
     ".": {

packages/vitest/rollup.config.js

@@ -32,6 +32,7 @@ const entries = {
   'worker': 'src/public/worker.ts',
   'module-runner': 'src/public/module-runner.ts',
   'module-evaluator': 'src/runtime/moduleRunner/moduleEvaluator.ts',
+  'nodejs-worker-loader.js': 'src/runtime/nodejsWorkerLoader.ts',
 
   // for performance reasons we bundle them separately so we don't import everything at once
   // 'worker': 'src/runtime/worker.ts',

packages/vitest/src/integrations/snapshot/environments/resolveSnapshotEnvironment.ts

@@ -1,17 +1,17 @@
 import type { SnapshotEnvironment } from '@vitest/snapshot/environment'
 import type { SerializedConfig } from '../../../runtime/config'
-import type { VitestModuleRunner } from '../../../runtime/moduleRunner/moduleRunner'
+import type { TestModuleRunner } from '../../../runtime/moduleRunner/testModuleRunner'
 
 export async function resolveSnapshotEnvironment(
   config: SerializedConfig,
-  executor: VitestModuleRunner,
+  moduleRunner: TestModuleRunner,
 ): Promise<SnapshotEnvironment> {
   if (!config.snapshotEnvironment) {
     const { VitestNodeSnapshotEnvironment } = await import('./node')
     return new VitestNodeSnapshotEnvironment()
   }
 
-  const mod = await executor.import(config.snapshotEnvironment)
+  const mod = await moduleRunner.import(config.snapshotEnvironment)
   if (typeof mod.default !== 'object' || !mod.default) {
     throw new Error(
       'Snapshot environment module must have a default export object with a shape of `SnapshotEnvironment`',

packages/vitest/src/node/cli/cli-config.ts

@@ -769,7 +769,7 @@
   experimental: {
     description: 'Experimental features.',
     argument: '<features>',
     subcommands: {
       fsModuleCache: {
         description: 'Enable caching of modules on the file system between reruns.',
       },
@@ -778,6 +778,9 @@
       printImportBreakdown: {
         description: 'Print import breakdown after the summary. If the reporter doesn\'t support summary, this will have no effect. Note that UI\'s "Module Graph" tab always has an import breakdown.',
       },
+      viteModuleRunner: {
+        description: 'Control whether Vitest uses Vite\'s module runner to run the code or fallback to the native `import`. (default: `true`)',
+      },
     },
   },
   // disable CLI options

packages/vitest/src/node/config/serializeConfig.ts

@@ -133,6 +133,8 @@ export function serializeConfig(project: TestProject): SerializedConfig {
     experimental: {
       fsModuleCache: config.experimental.fsModuleCache ?? false,
       printImportBreakdown: config.experimental.printImportBreakdown,
+      viteModuleRunner: config.experimental.viteModuleRunner ?? true,
+      nodeLoader: config.experimental.nodeLoader ?? true,
     },
   }
 }

packages/vitest/src/node/core.ts

@@ -24,6 +24,7 @@ import { version } from '../../package.json' with { type: 'json' }
 import { WebSocketReporter } from '../api/setup'
 import { distDir } from '../paths'
 import { wildcardPatternToRegExp } from '../utils/base'
+import { NativeModuleRunner } from '../utils/nativeModuleRunner'
 import { convertTasksToEvents } from '../utils/tasks'
 import { Traces } from '../utils/traces'
 import { astCollectTests, createFailedFileTask } from './ast-collect'
@@ -238,11 +239,13 @@ export class Vitest {
       this._tmpDir,
     )
     const environment = server.environments.__vitest__
-    this.runner = new ServerModuleRunner(
-      environment,
-      this._fetcher,
-      resolved,
-    )
+    this.runner = resolved.experimental.viteModuleRunner === false
+      ? new NativeModuleRunner(resolved.root)
+      : new ServerModuleRunner(
+          environment,
+          this._fetcher,
+          resolved,
+        )
 
     if (this.config.watch) {
       // hijack server restart

packages/vitest/src/node/plugins/workspace.ts

@@ -97,15 +97,21 @@ export function WorkspaceVitestPlugin(
           name: { label: name, color },
         }
 
+        vitestConfig.experimental ??= {}
+
         // always inherit the global `fsModuleCache` value even without `extends: true`
-        if (testConfig.experimental?.fsModuleCache == null && project.vitest.config.experimental?.fsModuleCache !== null) {
-          vitestConfig.experimental ??= {}
+        if (testConfig.experimental?.fsModuleCache == null && project.vitest.config.experimental?.fsModuleCache != null) {
           vitestConfig.experimental.fsModuleCache = project.vitest.config.experimental.fsModuleCache
         }
-        if (testConfig.experimental?.fsModuleCachePath == null && project.vitest.config.experimental?.fsModuleCachePath !== null) {
-          vitestConfig.experimental ??= {}
+        if (testConfig.experimental?.fsModuleCachePath == null && project.vitest.config.experimental?.fsModuleCachePath != null) {
           vitestConfig.experimental.fsModuleCachePath = project.vitest.config.experimental.fsModuleCachePath
         }
+        if (testConfig.experimental?.viteModuleRunner == null && project.vitest.config.experimental?.viteModuleRunner != null) {
+          vitestConfig.experimental.viteModuleRunner = project.vitest.config.experimental.viteModuleRunner
+        }
+        if (testConfig.experimental?.nodeLoader == null && project.vitest.config.experimental?.nodeLoader != null) {
+          vitestConfig.experimental.nodeLoader = project.vitest.config.experimental.nodeLoader
+        }
 
         return {
           base: '/',

packages/vitest/src/node/pools/rpc.ts

@@ -149,5 +149,36 @@ export function createMethodsRPC(project: TestProject, methodsOptions: MethodsOp
     getCountOfFailedTests() {
       return vitest.state.getCountOfFailedTests()
     },
+
+    ensureModuleGraphEntry(id, importer) {
+      const filepath = id.startsWith('file:') ? fileURLToPath(id) : id
+      const importerPath = importer.startsWith('file:') ? fileURLToPath(importer) : importer
+      // environment itself doesn't matter
+      const moduleGraph = project.vite.environments.__vitest__?.moduleGraph
+      if (!moduleGraph) {
+        // TODO: is it possible?
+        console.error('no module graph for', id)
+        return
+      }
+      const importerNode = moduleGraph.getModuleById(importerPath) || moduleGraph.createFileOnlyEntry(importerPath)
+      const moduleNode = moduleGraph.getModuleById(filepath) || moduleGraph.createFileOnlyEntry(filepath)
+
+      if (!moduleGraph.idToModuleMap.has(importerPath)) {
+        importerNode.id = importerPath
+        moduleGraph.idToModuleMap.set(importerPath, importerNode)
+      }
+      if (!moduleGraph.idToModuleMap.has(filepath)) {
+        moduleNode.id = filepath
+        moduleGraph.idToModuleMap.set(filepath, moduleNode)
+      }
+
+      // this is checked by the "printError" function - TODO: is there a better way?
+      moduleNode.transformResult = {
+        code: ' ',
+        map: null,
+      }
+      importerNode.importedModules.add(moduleNode)
+      moduleNode.importers.add(importerNode)
+    },
   }
 }

packages/vitest/src/node/project.ts

@@ -1,5 +1,5 @@
 import type { GlobOptions } from 'tinyglobby'
-import type { ViteDevServer, InlineConfig as ViteInlineConfig } from 'vite'
+import type { DevEnvironment, ViteDevServer, InlineConfig as ViteInlineConfig } from 'vite'
 import type { ModuleRunner } from 'vite/module-runner'
 import type { Typechecker } from '../typecheck/typechecker'
 import type { ProvidedContext } from '../types/general'
@@ -24,6 +24,7 @@ import pm from 'picomatch'
 import { glob } from 'tinyglobby'
 import { setup } from '../api/setup'
 import { createDefinesScript } from '../utils/config-helpers'
+import { NativeModuleRunner } from '../utils/nativeModuleRunner'
 import { isBrowserEnabled, resolveConfig } from './config/resolveConfig'
 import { serializeConfig } from './config/serializeConfig'
 import { createFetchModuleFunction } from './environments/fetchModule'
@@ -568,11 +569,21 @@ export class TestProject {
     )
 
     const environment = server.environments.__vitest__
-    this.runner = new ServerModuleRunner(
-      environment,
-      this._fetcher,
-      this._config,
-    )
+    this.runner = this._config.experimental.viteModuleRunner === false
+      ? new NativeModuleRunner(this._config.root)
+      : new ServerModuleRunner(
+          environment,
+          this._fetcher,
+          this._config,
+        )
+  }
+
+  /** @internal */
+  public _getViteEnvironments(): DevEnvironment[] {
+    return [
+      ...Object.values(this.browser?.vite.environments || {}),
+      ...Object.values(this.vite.environments || {}),
+    ]
   }
 
   private _serializeOverriddenConfig(): SerializedConfig {

packages/vitest/src/node/types/config.ts

@@ -854,6 +854,21 @@ export interface InlineConfig {
      * Enabling this will also show a breakdown by default in UI, but you can always press a button to toggle it.
      */
     printImportBreakdown?: boolean
+
+    /**
+     * Controls whether Vitest uses Vite's module runner to run the code or fallback to the native `import`.
+     *
+     * If Node.js cannot process the code, consider registering [module loader](https://nodejs.org/api/module.html#customization-hooks) via `execArgv`.
+     * @default true
+     */
+    viteModuleRunner?: boolean
+    /**
+     * If module runner is disabled, Vitest uses a module loader to transform files to support
+     * `import.meta.vitest` and `vi.mock`.
+     *
+     * If you don't use these features, you can disable this.
+     */
+    nodeLoader?: boolean
   }
 }
 

packages/vitest/src/node/watcher.ts

@@ -179,8 +179,9 @@ export class VitestWatcher {
     }
 
     const projects = this.vitest.projects.filter((project) => {
-      const moduleGraph = project.browser?.vite.moduleGraph || project.vite.moduleGraph
-      return moduleGraph.getModulesByFile(filepath)?.size
+      return project._getViteEnvironments().some(({ moduleGraph }) => {
+        return moduleGraph.getModulesByFile(filepath)?.size
+      })
     })
     if (!projects.length) {
       // if there are no modules it's possible that server was restarted
@@ -195,9 +196,8 @@ export class VitestWatcher {
     const files: string[] = []
 
     for (const project of projects) {
-      const mods = project.browser?.vite.moduleGraph.getModulesByFile(filepath)
-        || project.vite.moduleGraph.getModulesByFile(filepath)
-      if (!mods || !mods.size) {
+      const environmentMods = project._getViteEnvironments().map(({ moduleGraph }) => moduleGraph.getModulesByFile(filepath))
+      if (!environmentMods.length) {
         continue
       }
 
@@ -211,17 +211,19 @@ export class VitestWatcher {
       }
 
       let rerun = false
-      for (const mod of mods) {
-        mod.importers.forEach((i) => {
-          if (!i.file) {
-            return
-          }
-
-          const needsRerun = this.handleFileChanged(i.file)
-          if (needsRerun) {
-            rerun = true
-          }
-        })
+      for (const mods of environmentMods) {
+        for (const mod of mods || []) {
+          mod.importers.forEach((i) => {
+            if (!i.file) {
+              return
+            }
+
+            const needsRerun = this.handleFileChanged(i.file)
+            if (needsRerun) {
+              rerun = true
+            }
+          })
+        }
       }
 
       if (rerun) {

packages/vitest/src/public/module-runner.ts

@@ -10,5 +10,6 @@ export {
   type ContextModuleRunnerOptions,
   startVitestModuleRunner,
   VITEST_VM_CONTEXT_SYMBOL,
-} from '../runtime/moduleRunner/startModuleRunner'
+} from '../runtime/moduleRunner/startVitestModuleRunner'
+export type { TestModuleRunner } from '../runtime/moduleRunner/testModuleRunner'
 export { getWorkerState } from '../runtime/utils'

packages/vitest/src/public/worker.ts

@@ -1,2 +1,2 @@
-export { runBaseTests, setupEnvironment } from '../runtime/workers/base'
+export { runBaseTests, setupBaseEnvironment as setupEnvironment } from '../runtime/workers/base'
 export { init } from '../runtime/workers/init'

packages/vitest/src/runtime/config.ts

@@ -120,6 +120,8 @@ export interface SerializedConfig {
   experimental: {
     fsModuleCache: boolean
     printImportBreakdown: boolean | undefined
+    viteModuleRunner: boolean
+    nodeLoader: boolean
   }
 }