feat!: share the Vite server between inline projects (#10848)

Author: sheremet-va

docs/.vitepress/config.ts

@@ -542,6 +542,10 @@ export default ({ mode }: { mode: string }) => {
                 text: 'projects',
                 link: '/config/projects',
               },
+              {
+                text: 'sharedViteServer',
+                link: '/config/sharedviteserver',
+              },
               {
                 text: 'isolate',
                 link: '/config/isolate',

docs/api/advanced/test-project.md

@@ -98,7 +98,15 @@ It is based on the root of the project and its name. Note that the root path is
 
 ## vite
 
-This is project's [`ViteDevServer`](https://vite.dev/guide/api-javascript#vitedevserver). All projects have their own Vite servers.
+This is project's [`ViteDevServer`](https://vite.dev/guide/api-javascript#vitedevserver). Note that the server is not necessarily exclusive to this project: other projects can reuse it when the [`sharedViteServer`](/config/sharedviteserver) option applies, and browser instances of the same cluster share a single browser server.
+
+## sharedViteServer
+
+```ts
+const sharedViteServer: boolean
+```
+
+`true` when the project reuses the Vite server of the config that declared it instead of resolving its own (see the [`sharedViteServer`](/config/sharedviteserver) option). The project that owns the server reports `false` even when other projects reuse it. To detect any two projects sharing a server (including browser instances), compare their [`vite`](#vite) references.
 
 ## browser
 

docs/config/sharedviteserver.md

@@ -0,0 +1,74 @@
+---
+title: sharedViteServer | Config
+outline: deep
+---
+
+# sharedViteServer <CRoot />
+
+- **Type:** `boolean`
+- **Default:** `true`
+- **CLI:** `--sharedViteServer=false`
+
+Inline [projects](/guide/projects) that don't modify the Vite config reuse the Vite server of the config that declares them. Instead of resolving a new Vite config and creating a new server for every project, such projects share the declaring config's server and its transform cache, so shared source files are transformed once instead of once per project and tests run faster. The performance improvement varies depending on the number of inline projects and how many source files they have in common.
+
+This option _only_ applies to inline projects. Projects referenced as config files or directories always resolve their own Vite config and create their own server.
+
+A project still gets its own Vite server when it defines Vite-level options that change the server (`plugins`, `resolve`, and so on), when its `extends` doesn't point to the declaring config, or when it defines test options that affect the Vite config:
+
+- [`alias`](/config/alias)
+- [`browser`](/config/browser/enabled)
+- [`css`](/config/css)
+- [`deps.moduleDirectories`](/config/deps#deps-moduledirectories)
+- [`deps.optimizer`](/config/deps#deps-optimizer)
+- `mode`
+- [`root`](/config/root)
+
+Options like `env`, `setupFiles`, `server.deps`, or `environment` don't prevent sharing: every project keeps its own module resolution rules, module runner, and module instances on top of the shared server.
+
+The same applies to Vite-level values that don't change the server: an empty `plugins` list (`plugins: isCI ? [ciPlugin()] : []`) and `define`.
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    projects: [
+      // these projects share the root Vite server
+      { test: { name: 'unit', include: ['**/*.unit.test.ts'] } },
+      { test: { name: 'integration', include: ['**/*.integration.test.ts'] } },
+      // `define` doesn't create a new server, so this project also shares it
+      { define: { __DEV__: 'true' }, test: { name: 'dev' } },
+      // this project resolves its own Vite config because of `alias`
+      { test: { name: 'aliased', alias: { lib: './src/lib' } } },
+    ],
+  },
+})
+```
+
+::: tip
+If every project repeats the same `plugins` entry, move it to the declaring config. The projects inherit it from the shared server and keep sharing:
+
+```ts [vitest.config.ts]
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  // hoisted: instantiated once on the shared server
+  plugins: [react()],
+  test: {
+    projects: [
+      { test: { name: 'unit', include: ['**/*.unit.test.ts'] } },
+      { test: { name: 'integration', include: ['**/*.integration.test.ts'] } },
+    ],
+  },
+})
+```
+:::
+
+To see the decision for every project, including why a project resolves its own server, run Vitest with `DEBUG=vitest:projects`. API consumers can check whether a project reuses the declaring config's server via [`project.sharedViteServer`](/api/advanced/test-project#sharedviteserver).
+
+The option applies to every level: inline projects of a [nested projects container](/guide/projects#nested-projects) share the container's server the same way.
+
+::: warning
+When projects share a server, the declaring config file is executed once instead of once per project. Plugins are instantiated once, and their `config` hooks cannot observe per-project test options. If a plugin needs to behave differently per project, disable this option or don't share the server for that project (for example, set `extends: false` or define the project in its own config file).
+:::

docs/guide/cli-generated.md

@@ -930,6 +930,13 @@ Run only tests with the specified tags. You can use logical operators `&&` (and)
 
 Should Vitest throw an error if test has a tag that is not defined in the config. (default: `true`)
 
+### sharedViteServer
+
+- **CLI:** `--sharedViteServer`
+- **Config:** [sharedViteServer](/config/sharedviteserver)
+
+Let inline projects that don't modify the Vite config reuse the Vite server of the config that declares them. (default: `true`)
+
 ### experimental.importDurations.print
 
 - **CLI:** `--experimental.importDurations.print <boolean|on-warn>`

docs/guide/migration.md

@@ -157,6 +157,32 @@ Since the inherited `projects` paths resolve relative to the referenced config,
 
 Inline configurations continue to ignore the `projects` field at runtime, but it is now also excluded from their `ProjectConfig` type.
 
+### Inline Projects Share the Vite Server by Default
+
+Inline projects that don't modify the Vite config now reuse the Vite server of the config that declares them instead of resolving a new Vite config and creating a new server per project. This is controlled by the new [`sharedViteServer`](/config/sharedviteserver) option, which is enabled by default.
+
+Sharing the server means files are transformed once instead of once per project, so tests should now run faster: a config with several inline projects over the same codebase benefits the most, while a config with a single project won't see a difference.
+
+Note that this _only_ applies to inline projects. Projects referenced as config files or directories always resolve their own Vite config and create their own server, exactly as before.
+
+An inline project also still gets its own Vite server when it defines Vite-level options that change the server (`plugins`, `resolve`, and so on), a non-default `extends`, or test options that affect the Vite config: `alias`, `browser`, `css`, `deps.moduleDirectories`, `deps.optimizer`, `mode`, or `root`. Every project keeps its own module resolution rules, module runner, and module instances, so options like `env`, `setupFiles`, `server.deps`, or `environment` still resolve per project.
+
+The observable change: when the server is shared, the declaring config file is executed once instead of once per project, so its plugins are instantiated once and their `config` hooks no longer run for every project. If a plugin relies on being re-instantiated per project, disable the sharing:
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    sharedViteServer: false, // [!code ++]
+    projects: [
+      { test: { name: 'unit' } },
+      { test: { name: 'integration' } },
+    ],
+  },
+})
+```
+
 ### Hoisted Mocking Calls Must Be at the Top Level
 
 [`vi.mock`](/api/vi#vi-mock), [`vi.unmock`](/api/vi#vi-unmock), and [`vi.hoisted`](/api/vi#vi-hoisted) are hoisted to the top of the file and run before any surrounding code. Calling them inside a function, block, or `describe`/`test` callback previously only logged a warning. Vitest 5.0 now throws, because the call does not execute where it is written:

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

@@ -887,6 +887,9 @@ export const cliOptionsConfig: VitestCLIOptions = {
   strictTags: {
     description: 'Should Vitest throw an error if test has a tag that is not defined in the config. (default: `true`)',
   },
+  sharedViteServer: {
+    description: 'Let inline projects that don\'t modify the Vite config reuse the Vite server of the config that declares them. (default: `true`)',
+  },
 
   experimental: {
     description: 'Experimental features.',

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

@@ -1,19 +1,20 @@
 import type {
   InlineConfig,
   ResolvedConfig as ResolvedViteConfig,
+  Plugin as VitePlugin,
   UserConfig as ViteUserConfig,
 } from 'vite'
 import type { Logger } from '../logger'
-import type { BrowserContributionHolder } from '../plugins/browserLoader'
 import type {
   ApiConfig,
+  ConfigResolutionCaptures,
   ResolvedConfig,
   UserConfig,
 } from '../types/config'
 import type { CoverageOptions, CoverageReporterWithOptions } from '../types/coverage'
 import { existsSync, statSync } from 'node:fs'
 import { pathToFileURL } from 'node:url'
-import { deepMerge, slash, toArray } from '@vitest/utils/helpers'
+import { deepClone, deepMerge, slash, toArray } from '@vitest/utils/helpers'
 import { resolveModule } from 'local-pkg'
 import { join, normalize, relative, resolve } from 'pathe'
 import { isDynamicPattern } from 'tinyglobby'
@@ -28,10 +29,9 @@ import { wildcardPatternToRegExp } from '../../utils/base'
 import { isAgent, isCI, stdProvider } from '../../utils/env'
 import { getWorkersCountByPercentage } from '../../utils/workers'
 import { BrowserLoaderPlugin } from '../plugins/browserLoader'
-import { CliOverride } from '../plugins/cliOverride'
-import { VitestConfig } from '../plugins/config'
+import { ViteConfigPlugin } from '../plugins/config'
 import { VitestCorePlugin } from '../plugins/index'
-import { VitestConfigServer } from '../plugins/server'
+import { TestConfigPlugin } from '../plugins/testConfig'
 import { resolveFsAllow } from '../plugins/utils'
 import { resolveProjectEntries } from '../projects/resolveProjects'
 import { withLabel } from '../reporters/renderers/utils'
@@ -997,6 +997,7 @@ export function resolveTestConfig(
   resolved.hookTimeout ??= resolved.browser.enabled ? 30_000 : 10_000
 
   resolved.experimental ??= {} as any
+  resolved.sharedViteServer ??= true
   if (resolved.experimental.openTelemetry?.sdkPath) {
     const sdkPath = resolve(
       resolved.root,
@@ -1065,6 +1066,40 @@ export function resolveTestConfig(
   return resolved
 }
 
+/**
+ * Captures `config.test` before any Vitest plugin modifies it. Inline projects
+ * that share this config's Vite server resolve against the captured value
+ * instead of re-executing the config file (`sharedViteServer`).
+ *
+ * Must be the first inline plugin. The consumer must clear
+ * `captures.rawTestConfig` after storing it because the server retains the plugin.
+ */
+export function CaptureRawTestConfig(captures: ConfigResolutionCaptures, capture: boolean | undefined): VitePlugin {
+  return {
+    name: 'vitest:capture-raw-test-config',
+    enforce: 'pre',
+    config: {
+      order: 'pre',
+      handler(config) {
+        if (!(capture ?? config.test?.sharedViteServer ?? true)) {
+          return
+        }
+        const { projects, ...test } = (config.test ?? {}) as UserConfig
+        // the captured config is only read when this config's inline
+        // projects are resolved; without `projects` there is nothing to
+        // read it (`injectTestProjects` then resolves through Vite instead)
+        if (projects === undefined) {
+          return
+        }
+        // cloned so mutations from later hooks and from the test-config
+        // resolution never reach the captured value; `projects` is left out
+        // because it is never inherited and can be the largest part of the config
+        captures.rawTestConfig = deepClone(test) as UserConfig
+      },
+    },
+  }
+}
+
 function resolveConfigPath(root: string, options: UserConfig) {
   if (options.config === false) {
     return false
@@ -1081,25 +1116,27 @@ export async function resolveConfig(
   pluginsHarness: PluginHarness = new PluginHarness(),
 ): Promise<ResolvedViteConfig> {
   // We clone CLI Options and Vite overrides to reuse when a watch mode is triggered.
-  const cliOptionsCopy = deepMerge({}, options)
-  const viteOverridesCopy = deepMerge({}, viteOverrides)
+  const cliOptionsCopy = deepMerge({}, options) as UserConfig
+  const viteOverridesCopy = deepMerge({}, viteOverrides) as ViteUserConfig
   const root = resolve(options.root || process.cwd())
   const configPath = resolveConfigPath(root, options)
   options.config = configPath
   options.root = root
 
-  const rootBrowserHolder: BrowserContributionHolder = {}
+  const captures: ConfigResolutionCaptures = {}
   const inlineConfig: InlineConfig = mergeConfig(
     {
       configFile: configPath,
       configLoader: options.configLoader,
       mode: options.mode || 'test',
       plugins: [
-        CliOverride(cliOptionsCopy),
-        ...VitestConfigServer(pluginsHarness),
-        ...VitestConfig(pluginsHarness),
+        // the capture hook runs before `vitest:config:cli`, so `--sharedViteServer`
+        // has to be passed directly instead of being read from `config.test`
+        CaptureRawTestConfig(captures, cliOptionsCopy.sharedViteServer),
+        ...TestConfigPlugin(pluginsHarness, captures, cliOptionsCopy),
+        ...ViteConfigPlugin(pluginsHarness),
         ...VitestCorePlugin(pluginsHarness, options),
-        ...BrowserLoaderPlugin(rootBrowserHolder, pluginsHarness),
+        ...BrowserLoaderPlugin(captures, pluginsHarness),
       ],
     } satisfies InlineConfig,
     mergeConfig(viteOverrides, { root }),
@@ -1152,7 +1189,25 @@ export async function resolveConfig(
 
   rootConfig.cliOptions = cliOptionsCopy
   rootConfig.viteOverrides = viteOverridesCopy
-  rootConfig._browserContribution = rootBrowserHolder.contribution
+  rootConfig._browserContribution = captures.browserContribution
+  // projects never inherit `tagsFilter` and `browser` from the programmatic
+  // config (see `inheritRootViteOverrides`), so remove them from the base too
+  if (captures.rawTestConfig) {
+    const overridesTest = (viteOverridesCopy as ViteUserConfig).test as UserConfig | undefined
+    if (overridesTest?.tagsFilter !== undefined) {
+      delete captures.rawTestConfig.tagsFilter
+    }
+    if (overridesTest?.browser !== undefined) {
+      delete captures.rawTestConfig.browser
+    }
+  }
+  // the root keeps the config for the whole session so `injectTestProjects`
+  // can resolve shared-server projects at any point
+  rootConfig._rawTestConfig = captures.rawTestConfig
+  rootConfig._moduleRunnerOptions = captures.moduleRunnerOptions
+  // `captures` lives as long as the server that keeps its plugins,
+  // so it should not hold onto the config
+  captures.rawTestConfig = undefined
 
   rootConfig.resolvedProjects = await resolveProjectEntries(
     pluginsHarness,

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

@@ -6,16 +6,11 @@ import type {
 import type { PluginHarness } from '../config/pluginHarness'
 import type { Vitest } from '../core'
 import type {
-  BrowserServerContribution,
   ParentProjectBrowser,
 } from '../types/browser'
-import type { ResolvedConfig, ResolvedProjectEntry } from '../types/config'
+import type { ConfigResolutionCaptures, ResolvedConfig, ResolvedProjectEntry } from '../types/config'
 import { createViteServer } from '../vite'
 
-export interface BrowserContributionHolder {
-  contribution?: BrowserServerContribution
-}
-
 function sortPluginsByEnforce(plugins: VitePlugin[]): VitePlugin[] {
   const pre: VitePlugin[] = []
   const normal: VitePlugin[] = []
@@ -35,7 +30,7 @@ function sortPluginsByEnforce(plugins: VitePlugin[]): VitePlugin[] {
 }
 
 export function BrowserLoaderPlugin(
-  holder: BrowserContributionHolder,
+  captures: ConfigResolutionCaptures,
   harness: PluginHarness,
 ): VitePlugin[] {
   return [
@@ -60,12 +55,12 @@ export function BrowserLoaderPlugin(
           throw new Error(`Browser Mode was enabled, but provider was not specified anywhere. See https://vitest.dev/guide/browser/#configuration`)
         }
         const contribution = await provider.serverFactory()
-        holder.contribution = contribution
+        captures.browserContribution = contribution
         const browserConfig = await contribution.config(viteConfig, harness)
         return browserConfig
       },
       applyToEnvironment(environment) {
-        const contribution = holder.contribution
+        const contribution = captures.browserContribution
         if (contribution && environment.name === 'client') {
           // `post` browser plugins are injected by `vitest:browser:loader:post`
           // instead, so they run after the `post` plugins of the main pipeline
@@ -81,21 +76,21 @@ export function BrowserLoaderPlugin(
       configureServer: {
         order: 'pre',
         async handler(server) {
-          await holder.contribution?.configureServer(server)
+          await captures.browserContribution?.configureServer(server)
         },
       },
       transformIndexHtml: {
         order: 'pre',
         async handler(html, ctx) {
-          return holder.contribution?.transformIndexHtml(ctx)
+          return captures.browserContribution?.transformIndexHtml(ctx)
         },
       },
     },
     {
       name: 'vitest:browser:loader:post',
       enforce: 'post',
       applyToEnvironment(environment) {
-        const contribution = holder.contribution
+        const contribution = captures.browserContribution
         if (contribution && environment.name === 'client') {
           return sortPluginsByEnforce(
             contribution.plugins.filter(plugin => plugin.enforce === 'post'),