chore: warning about ssr cjs format removal (#13827)

Co-authored-by: Bjorn Lu <[email protected]>
vitejs · Jul 14, 2023 · 4646e9f · 4646e9f
1 parent b6155a1
commit 4646e9f
Show file tree

Hide file tree

Showing 4 changed files with 19 additions and 0 deletions.
diff --git a/docs/config/ssr-options.md b/docs/config/ssr-options.md
@@ -24,6 +24,7 @@ Build target for the SSR server.
 ## ssr.format
 
 - **Experimental**
+- **Deprecated** Only ESM output will be supported in Vite 5.
 - **Type:** `'esm' | 'cjs'`
 - **Default:** `esm`
 

diff --git a/docs/guide/ssr.md b/docs/guide/ssr.md
@@ -270,3 +270,7 @@ Use a post hook so that your SSR middleware runs _after_ Vite's middlewares.
 ## SSR Format
 
 By default, Vite generates the SSR bundle in ESM. There is experimental support for configuring `ssr.format`, but it isn't recommended. Future efforts around SSR development will be based on ESM, and CommonJS remains available for backward compatibility. If using ESM for SSR isn't possible in your project, you can set `legacy.buildSsrCjsExternalHeuristics: true` to generate a CJS bundle using the same [externalization heuristics of Vite v2](https://v2.vitejs.dev/guide/ssr.html#ssr-externals).
+
+:::warning Warning
+Experimental `legacy.buildSsrCjsExternalHeuristics` and `ssr.format: 'cjs'` are going to be removed in Vite 5. Find more information and give feedback [in this discussion](https://github.com/vitejs/vite/discussions/13816).
+:::
diff --git a/packages/vite/src/node/config.ts b/packages/vite/src/node/config.ts
@@ -837,6 +837,19 @@ assetFileNames isn't equal for every build.rollupOptions.output. A single patter
     }
   }
 
+  // Warn about removal of experimental features
+  if (
+    config.legacy?.buildSsrCjsExternalHeuristics ||
+    config.ssr?.format === 'cjs'
+  ) {
+    resolved.logger.warn(
+      colors.yellow(`
+(!) Experimental legacy.buildSsrCjsExternalHeuristics and ssr.format: 'cjs' are going to be removed in Vite 5. 
+    Find more information and give feedback at https://github.com/vitejs/vite/discussions/13816.
+`),
+    )
+  }
+
   return resolved
 }
 

diff --git a/packages/vite/src/node/ssr/index.ts b/packages/vite/src/node/ssr/index.ts
@@ -20,6 +20,7 @@ export interface SSROptions {
    * left marked as experimental to give users more time to update to ESM. CJS builds requires
    * complex externalization heuristics that aren't present in the ESM format.
    * @experimental
+   * @deprecated
    * @default 'esm'
    */
   format?: SSRFormat