feat(ssr): support for ssr.resolve.conditions and ssr.resolve.externalConditions options (#14498)

Author: Marc MacLeod

docs/config/ssr-options.md

@@ -20,3 +20,19 @@ Prevent listed dependencies from being externalized for SSR. If `true`, no depen
 - **Default:** `node`
 
 Build target for the SSR server.
+
+## ssr.resolve.conditions
+
+- **Type:** `string[]`
+- **Related:** [Resolve Conditions](./shared-options.md#resolve-conditions)
+
+Defaults to the the root [`resolve.conditions`](./shared-options.md#resolve-conditions).
+
+These conditions are used in the plugin pipeline, and only affect non-externalized dependencies during the SSR build. Use `ssr.resolve.externalConditions` to affect externalized imports.
+
+## ssr.resolve.externalConditions
+
+- **Type:** `string[]`
+- **Default:** `[]`
+
+Conditions that are used during ssr import (including `ssrLoadModule`) of externalized dependencies.

docs/guide/ssr.md

@@ -259,6 +259,10 @@ In some cases like `webworker` runtimes, you might want to bundle your SSR build
 - Treat all dependencies as `noExternal`
 - Throw an error if any Node.js built-ins are imported
 
+## SSR Resolve Conditions
+
+By default package entry resolution will use the conditions set in [`resolve.conditions`](../config/shared-options.md#resolve-conditions) for the SSR build. You can use [`ssr.resolve.conditions`](../config/ssr-options.md#ssr-resolve-conditions) and [`ssr.resolve.externalConditions`](../config/ssr-options.md#ssr-resolve-externalconditions) to customize this behavior.
+
 ## Vite CLI
 
 The CLI commands `$ vite dev` and `$ vite preview` can also be used for SSR apps. You can add your SSR middlewares to the development server with [`configureServer`](/guide/api-plugin#configureserver) and to the preview server with [`configurePreviewServer`](/guide/api-plugin#configurepreviewserver).

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

@@ -173,10 +173,17 @@ export function resolvePlugin(resolveOptions: InternalResolveOptions): Plugin {
       const isRequire: boolean =
         resolveOpts?.custom?.['node-resolve']?.isRequire ?? false
 
+      // end user can configure different conditions for ssr and client.
+      // falls back to client conditions if no ssr conditions supplied
+      const ssrConditions =
+        resolveOptions.ssrConfig?.resolve?.conditions ||
+        resolveOptions.conditions
+
       const options: InternalResolveOptions = {
         isRequire,
         ...resolveOptions,
         scan: resolveOpts?.scan ?? resolveOptions.scan,
+        conditions: ssr ? ssrConditions : resolveOptions.conditions,
       }
 
       const resolvedImports = resolveSubpathImports(

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

@@ -7,12 +7,14 @@ export type SsrDepOptimizationOptions = DepOptimizationConfig
 export interface SSROptions {
   noExternal?: string | RegExp | (string | RegExp)[] | true
   external?: string[]
+
   /**
    * Define the target for the ssr build. The browser field in package.json
    * is ignored for node but used if webworker is the target
    * @default 'node'
    */
   target?: SSRTarget
+
   /**
    * Control over which dependencies are optimized during SSR and esbuild options
    * During build:
@@ -22,6 +24,24 @@ export interface SSROptions {
    * @experimental
    */
   optimizeDeps?: SsrDepOptimizationOptions
+
+  resolve?: {
+    /**
+     * Conditions that are used in the plugin pipeline. The default value is the root config's `resolve.conditions`.
+     *
+     * Use this to override the default ssr conditions for the ssr build.
+     *
+     * @default rootConfig.resolve.conditions
+     */
+    conditions?: string[]
+
+    /**
+     * Conditions that are used during ssr import (including `ssrLoadModule`) of externalized dependencies.
+     *
+     * @default []
+     */
+    externalConditions?: string[]
+  }
 }
 
 export interface ResolvedSSROptions extends SSROptions {

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

@@ -40,11 +40,14 @@ export function createIsConfiguredAsSsrExternal(
     typeof noExternal !== 'boolean' &&
     createFilter(undefined, noExternal, { resolve: false })
 
+  const targetConditions = config.ssr.resolve?.externalConditions || []
+
   const resolveOptions: InternalResolveOptions = {
     ...config.resolve,
     root,
     isProduction: false,
     isBuild: true,
+    conditions: targetConditions,
   }
 
   const isExternalizable = (

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

@@ -123,19 +123,23 @@ async function instantiateModule(
     isProduction,
     resolve: { dedupe, preserveSymlinks },
     root,
+    ssr,
   } = server.config
 
+  const overrideConditions = ssr.resolve?.externalConditions || []
+
   const resolveOptions: InternalResolveOptionsWithOverrideConditions = {
     mainFields: ['main'],
     browserField: true,
     conditions: [],
-    overrideConditions: ['production', 'development'],
+    overrideConditions: [...overrideConditions, 'production', 'development'],
     extensions: ['.js', '.cjs', '.json'],
     dedupe,
     preserveSymlinks,
     isBuild: false,
     isProduction,
     root,
+    ssrConfig: ssr,
   }
 
   // Since dynamic imports can happen in parallel, we need to
@@ -281,6 +285,8 @@ async function nodeImport(
         ? { ...resolveOptions, tryEsmOnly: true }
         : resolveOptions,
       false,
+      undefined,
+      true,
     )
     if (!resolved) {
       const err: any = new Error(

playground/ssr-conditions/__tests__/serve.ts

@@ -0,0 +1,35 @@
+// this is automatically detected by playground/vitestSetup.ts and will replace
+// the default e2e test serve behavior
+
+import path from 'node:path'
+import kill from 'kill-port'
+import { hmrPorts, ports, rootDir } from '~utils'
+
+export const port = ports['ssr-conditions']
+
+export async function serve(): Promise<{ close(): Promise<void> }> {
+  await kill(port)
+
+  const { createServer } = await import(path.resolve(rootDir, 'server.js'))
+  const { app, vite } = await createServer(rootDir, hmrPorts['ssr-conditions'])
+
+  return new Promise((resolve, reject) => {
+    try {
+      const server = app.listen(port, () => {
+        resolve({
+          // for test teardown
+          async close() {
+            await new Promise((resolve) => {
+              server.close(resolve)
+            })
+            if (vite) {
+              await vite.close()
+            }
+          },
+        })
+      })
+    } catch (e) {
+      reject(e)
+    }
+  })
+}

playground/ssr-conditions/__tests__/ssr-conditions.spec.ts

@@ -0,0 +1,27 @@
+import { expect, test } from 'vitest'
+import { port } from './serve'
+import { page } from '~utils'
+
+const url = `http://localhost:${port}`
+
+test('ssr.resolve.conditions affect non-externalized imports during ssr', async () => {
+  await page.goto(url)
+  expect(await page.textContent('.no-external-react-server')).toMatch(
+    'node.unbundled.js',
+  )
+})
+
+test('ssr.resolve.externalConditions affect externalized imports during ssr', async () => {
+  await page.goto(url)
+  expect(await page.textContent('.external-react-server')).toMatch('edge.js')
+})
+
+test('ssr.resolve settings do not affect non-ssr imports', async () => {
+  await page.goto(url)
+  expect(await page.textContent('.browser-no-external-react-server')).toMatch(
+    'default.js',
+  )
+  expect(await page.textContent('.browser-external-react-server')).toMatch(
+    'default.js',
+  )
+})

playground/ssr-conditions/external/browser.js

@@ -0,0 +1 @@
+export default 'browser.js'

playground/ssr-conditions/external/default.js

@@ -0,0 +1 @@
+export default 'default.js'