feat(ssr): support external true (#10939)

Author: bluwy

docs/config/ssr-options.md

@@ -2,17 +2,25 @@
 
 ## ssr.external
 
-- **Type:** `string[]`
+- **Type:** `string[] | true`
 - **Related:** [SSR Externals](/guide/ssr#ssr-externals)
 
-Force externalize dependencies for SSR.
+Externalize the given dependencies and their transitive dependencies for SSR. By default, all dependencies are externalized except for linked dependencies (for HMR). If you prefer to externalize the linked dependency, you can pass its name to this option.
+
+If `true`, all dependencies including linked dependencies are externalized.
+
+Note that the explicitly listed dependencies (using `string[]` type) will always take priority if they're also listed in `ssr.noExternal` (using any type).
 
 ## ssr.noExternal
 
 - **Type:** `string | RegExp | (string | RegExp)[] | true`
 - **Related:** [SSR Externals](/guide/ssr#ssr-externals)
 
-Prevent listed dependencies from being externalized for SSR. If `true`, no dependencies are externalized.
+Prevent listed dependencies from being externalized for SSR, which they will get bundled in build. By default, only linked dependencies are not externalized (for HMR). If you prefer to externalize the linked dependency, you can pass its name to the `ssr.external` option.
+
+If `true`, no dependencies are externalized. However, dependencies explicitly listed in `ssr.external` (using `string[]` type) can take priority and still be externalized.
+
+Note that if both `ssr.noExternal: true` and `ssr.external: true` are configured, `ssr.noExternal` takes priority and no dependencies are externalized.
 
 ## ssr.target
 

packages/vite/src/node/ssr/__tests__/fixtures/cjs-ssr-dep/index.js

@@ -0,0 +1,4 @@
+// eslint-disable-next-line no-undef
+module.exports = {
+  hello: () => 'world',
+}

packages/vite/src/node/ssr/__tests__/fixtures/cjs-ssr-dep/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@vitejs/cjs-ssr-dep",
+  "private": true,
+  "version": "0.0.0"
+}

packages/vite/src/node/ssr/__tests__/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@vitejs/unit-ssr",
+  "private": true,
+  "version": "0.0.0",
+  "dependencies": {
+    "@vitejs/cjs-ssr-dep": "link:./fixtures/cjs-ssr-dep"
+  }
+}

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

@@ -0,0 +1,29 @@
+import { fileURLToPath } from 'node:url'
+import { describe, expect, test } from 'vitest'
+import type { SSROptions } from '..'
+import { resolveConfig } from '../../config'
+import { createIsConfiguredAsSsrExternal } from '../ssrExternal'
+
+describe('createIsConfiguredAsSsrExternal', () => {
+  test('default', async () => {
+    const isExternal = await createIsExternal()
+    expect(isExternal('@vitejs/cjs-ssr-dep')).toBe(false)
+  })
+
+  test('force external', async () => {
+    const isExternal = await createIsExternal({ external: true })
+    expect(isExternal('@vitejs/cjs-ssr-dep')).toBe(true)
+  })
+})
+
+async function createIsExternal(ssrConfig?: SSROptions) {
+  const resolvedConfig = await resolveConfig(
+    {
+      configFile: false,
+      root: fileURLToPath(new URL('./', import.meta.url)),
+      ssr: ssrConfig,
+    },
+    'serve',
+  )
+  return createIsConfiguredAsSsrExternal(resolvedConfig)
+}

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

@@ -6,7 +6,7 @@ export type SsrDepOptimizationOptions = DepOptimizationConfig
 
 export interface SSROptions {
   noExternal?: string | RegExp | (string | RegExp)[] | true
-  external?: string[]
+  external?: string[] | true
 
   /**
    * Define the target for the ssr build. The browser field in package.json

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

@@ -87,34 +87,35 @@ export function createIsConfiguredAsSsrExternal(
   // Returns true if it is configured as external, false if it is filtered
   // by noExternal and undefined if it isn't affected by the explicit config
   return (id: string, importer?: string) => {
-    const { ssr } = config
-    if (ssr) {
-      if (
-        // If this id is defined as external, force it as external
-        // Note that individual package entries are allowed in ssr.external
-        ssr.external?.includes(id)
-      ) {
-        return true
-      }
-      const pkgName = getNpmPackageName(id)
-      if (!pkgName) {
-        return isExternalizable(id, importer)
-      }
-      if (
-        // A package name in ssr.external externalizes every
-        // externalizable package entry
-        ssr.external?.includes(pkgName)
-      ) {
-        return isExternalizable(id, importer, true)
-      }
-      if (typeof noExternal === 'boolean') {
-        return !noExternal
-      }
-      if (noExternalFilter && !noExternalFilter(pkgName)) {
-        return false
-      }
+    if (
+      // If this id is defined as external, force it as external
+      // Note that individual package entries are allowed in ssr.external
+      ssr.external !== true &&
+      ssr.external?.includes(id)
+    ) {
+      return true
     }
-    return isExternalizable(id, importer)
+    const pkgName = getNpmPackageName(id)
+    if (!pkgName) {
+      return isExternalizable(id, importer)
+    }
+    if (
+      // A package name in ssr.external externalizes every
+      // externalizable package entry
+      ssr.external !== true &&
+      ssr.external?.includes(pkgName)
+    ) {
+      return isExternalizable(id, importer, true)
+    }
+    if (typeof noExternal === 'boolean') {
+      return !noExternal
+    }
+    if (noExternalFilter && !noExternalFilter(pkgName)) {
+      return false
+    }
+    // If `ssr.external: true`, all will be externalized by default, regardless if
+    // it's a linked package
+    return isExternalizable(id, importer, ssr.external === true)
   }
 }
 

pnpm-lock.yaml

@@ -1,3 +1,4 @@
 packages:
   - 'packages/*'
   - 'playground/**'
+  - 'packages/**/__tests__/**'