feat: legacy options to revert to v2 strategies

docs/guide/migration.md

@@ -27,27 +27,40 @@ A small fraction of users will now require using [@vitejs/plugin-legacy](https:/
   - `build.polyfillDynamicImport` (use [`@vitejs/plugin-legacy`](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) for browsers without dynamic import support)
   - `optimizeDeps.keepNames` (switch to [`optimizeDeps.esbuildOptions.keepNames`](../config/dep-optimization-options.md#optimizedepsesbuildoptions))
 
-## Dev Server Changes
+## Achitecture changes and legacy Options
+
+This section describes the biggest architecture changes in Vite v3. To allow projects to migrate from v2 in case of a compat issue, legacy options have been added to revert to the Vite v2 strategies.
+
+:::warning
+These options are marked as experimental and deprecated. They may be removed in a future v3 minor without respecting semver. Please pin the Vite version when using them.
+
+- `legacy.devDepsScanner`
+- `legacy.buildRollupPluginCommonjs`
+- `legacy.buildSsrCjsExternalHeuristics`
+
+:::
+
+### Dev Server Changes
 
 Vite's default dev server port is now 5173. You can use [`server.port`](../config/server-options.md#server-port) to set it to 3000.
 
 Vite's default dev server host is now `localhost`. You can use [`server.host`](../config/server-options.md#server-host) to set it to `127.0.0.1`.
 
 Vite optimizes dependencies with esbuild to both convert CJS-only deps to ESM and to reduce the number of modules the browser needs to request. In v3, the default strategy to discover and batch dependencies has changed. Vite no longer pre-scans user code with esbuild to get an initial list of dependencies on cold start. Instead, it delays the first dependency optimization run until every imported user module on load is processed.
 
-To get back the v2 strategy, you can use [`optimizeDeps.devScan`](../config/dep-optimization-options.md#optimizedepsdevscan).
+To get back the v2 strategy, you can use `legacy.devDepsScanner`.
 
-## Build Changes
+### Build Changes
 
 In v3, Vite uses esbuild to optimize dependencies by default. Doing so, it removes one of the most significant differences between dev and prod present in v2. Because esbuild converts CJS-only dependencies to ESM, [`@rollupjs/plugin-commonjs`](https://github.com/rollup/plugins/tree/master/packages/commonjs) is no longer used.
 
-If you need to get back to the v2 strategy, you can use [`optimizeDeps.disabled: 'build'`](../config/dep-optimization-options.md#optimizedepsdisabled).
+If you need to get back to the v2 strategy, you can use `legacy.buildRollupPluginCommonjs`.
 
-## SSR Changes
+### SSR Changes
 
 Vite v3 uses ESM for the SSR build by default. When using ESM, the [SSR externalization heuristics](https://vitejs.dev/guide/ssr.html#ssr-externals) are no longer needed. By default, all dependencies are externalized. You can use [`ssr.noExternal`](../config/ssr-options.md#ssrnoexternal) to control what dependencies to include in the SSR bundle.
 
-If using ESM for SSR isn't possible in your project, you can set `ssr.format: 'cjs'` to generate a CJS bundle. In this case, the same externalization strategy of Vite v2 will be used.
+If using ESM for SSR isn't possible in your project, you can set `legacy.buildSsrCjsExternalHeuristics` to generate a CJS bundle using the same externalization strategy of Vite v2.
 
 ## General Changes
 

packages/vite/src/node/build.ts

@@ -306,7 +306,7 @@ export function resolveBuildPlugins(config: ResolvedConfig): {
     pre: [
       ...(options.watch ? [ensureWatchPlugin()] : []),
       watchPackageDataPlugin(config),
-      ...(!isDepsOptimizerEnabled(config)
+      ...(config.legacy?.buildRollupPluginCommonjs
         ? [commonjsPlugin(options.commonjsOptions)]
         : []),
       dataURIPlugin(),
@@ -398,7 +398,7 @@ async function doBuild(
   // In CJS, we can pass the externals to rollup as is. In ESM, we need to
   // do it in the resolve plugin so we can add the resolved extension for
   // deep node_modules imports
-  if (ssr && config.ssr?.format === 'cjs') {
+  if (ssr && config.legacy?.buildSsrCjsExternalHeuristics) {
     external = await cjsSsrResolveExternal(config, userExternal)
   }
 

packages/vite/src/node/config.ts

@@ -157,11 +157,18 @@ export interface UserConfig {
   /**
    * Experimental features
    *
-   * Features under this field are addressed to be changed that might NOT follow semver.
+   * Features under this field could change in the future and might NOT follow semver.
    * Please be careful and always pin Vite's version when using them.
    * @experimental
    */
   experimental?: ExperimentalOptions
+  /**
+   * Legacy options
+   *
+   * Features under this field only follow semver for patches, they could be removed in a
+   * future minor version. Please always pin Vite's version to a minor when using them.
+   */
+  legacy?: LegacyOptions
   /**
    * Log level.
    * Default: 'info'
@@ -225,6 +232,33 @@ export interface ExperimentalOptions {
   importGlobRestoreExtension?: boolean
 }
 
+export interface LegacyOptions {
+  /**
+   * Revert vite dev to the v2.9 strategy. Enable esbuild based deps scanner.
+   *
+   * @experimental
+   * @deprecated
+   * @default false
+   */
+  devDepsScanner?: boolean
+  /**
+   * Revert vite build to the v2.9 strategy. Disable esbuild deps optimization and adds `@rollup/plugin-commonjs`
+   *
+   * @experimental
+   * @deprecated
+   * @default false
+   */
+  buildRollupPluginCommonjs?: boolean
+  /**
+   * Revert vite build --ssr to the v2.9 strategy. Use CJS SSR build and v2.9 externalization heuristics
+   *
+   * @experimental
+   * @deprecated
+   * @default false
+   */
+  buildSsrCjsExternalHeuristics?: boolean
+}
+
 export interface ResolveWorkerOptions {
   format: 'es' | 'iife'
   plugins: Plugin[]
@@ -467,7 +501,11 @@ export async function resolveConfig(
       : ''
 
   const server = resolveServerOptions(resolvedRoot, config.server, logger)
-  const ssr = resolveSSROptions(config.ssr)
+  let ssr = resolveSSROptions(config.ssr)
+  if (config.legacy?.buildSsrCjsExternalHeuristics) {
+    if (ssr) ssr.format = 'cjs'
+    else ssr = { target: 'node', format: 'cjs' }
+  }
 
   const optimizeDeps = config.optimizeDeps || {}
 
@@ -517,6 +555,15 @@ export async function resolveConfig(
     spa: config.spa ?? true
   }
 
+  if (resolved.legacy?.buildRollupPluginCommonjs) {
+    const optimizerDisabled = resolved.optimizeDeps.disabled
+    if (!optimizerDisabled) {
+      resolved.optimizeDeps.disabled = 'build'
+    } else if (optimizerDisabled === 'dev') {
+      resolved.optimizeDeps.disabled = true // Also disabled during build
+    }
+  }
+
   // Some plugins that aren't intended to work in the bundling of workers (doing post-processing at build time for example).
   // And Plugins may also have cached that could be corrupted by being used in these extra rollup calls.
   // So we need to separate the worker plugin from the plugin that vite needs to run.

packages/vite/src/node/optimizer/index.ts

@@ -72,13 +72,6 @@ export interface DepOptimizationOptions {
    * vite project root. This will overwrite default entries inference.
    */
   entries?: string | string[]
-  /**
-   * Enable esbuild based scan phase, to get back to the optimized deps discovery
-   * strategy used in Vite v2
-   * @default false
-   * @experimental
-   */
-  devScan?: boolean
   /**
    * Force optimize listed dependencies (must be resolvable import paths,
    * cannot be globs).

packages/vite/src/node/optimizer/optimizer.ts

@@ -50,7 +50,7 @@ export async function initDepsOptimizer(
   const { logger } = config
   const isBuild = config.command === 'build'
 
-  const scan = config.command !== 'build' && config.optimizeDeps.devScan
+  const scan = config.command !== 'build' && config.legacy?.devDepsScanner
 
   const sessionTimestamp = Date.now().toString()
 

packages/vite/src/node/plugins/importAnalysis.ts

@@ -370,7 +370,7 @@ export function importAnalysisPlugin(config: ResolvedConfig): Plugin {
           }
           // skip ssr external
           if (ssr) {
-            if (config.ssr?.format === 'cjs') {
+            if (config.legacy?.buildSsrCjsExternalHeuristics) {
               if (cjsShouldExternalizeForSSR(specifier, server._ssrExternals)) {
                 continue
               }
@@ -621,7 +621,7 @@ export function importAnalysisPlugin(config: ResolvedConfig): Plugin {
             // Unexpected error, log the issue but avoid an unhandled exception
             config.logger.error(e.message)
           })
-          if (depsOptimizer && !config.optimizeDeps.devScan) {
+          if (depsOptimizer && !config.legacy?.devDepsScanner) {
             depsOptimizer.delayDepsOptimizerUntil(id, () => request)
           }
         })

packages/vite/src/node/ssr/ssrExternal.ts

@@ -167,8 +167,8 @@ function createIsSsrExternal(
   }
 }
 
-// When ssr.format is 'cjs', this function is used reverting to the Vite 2.9
-// SSR externalization heuristics
+// When config.experimental.buildSsrCjsExternalHeuristics is enabled, this function
+// is used reverting to the Vite 2.9 SSR externalization heuristics
 function cjsSsrCollectExternals(
   root: string,
   preserveSymlinks: boolean | undefined,