feat!: deprecate cjs node api (#14278)

Author: bluwy

docs/guide/troubleshooting.md

@@ -4,6 +4,35 @@ See [Rollup's troubleshooting guide](https://rollupjs.org/troubleshooting/) for
 
 If the suggestions here don't work, please try posting questions on [GitHub Discussions](https://github.com/vitejs/vite/discussions) or in the `#help` channel of [Vite Land Discord](https://chat.vitejs.dev).
 
+## CJS
+
+### Vite CJS Node API deprecated
+
+The CJS build of Vite's Node API is deprecated and will be removed in Vite 6. See the [GitHub discussion](https://github.com/vitejs/vite/discussions/13928) for more context. You should update your files or frameworks to import the ESM build of Vite instead.
+
+In a basic Vite project, make sure:
+
+1. The `vite.config.js` file content is using the ESM syntax.
+2. The closest `package.json` file has `"type": "module"`, or use the `.mjs` extension, e.g. `vite.config.mjs`.
+
+For other projects, there are a few general approaches:
+
+- **Configure ESM as default, opt-in to CJS if needed:** Add `"type": "module"` in the project `package.json`. All `*.js` files are now interpreted as ESM and needs to use the ESM syntax. You can rename a file with the `.cjs` extension to keep using CJS instead.
+- **Keep CJS as default, opt-in to ESM if needed:** If the project `package.json` does not have `"type": "module"`, all `*.js` files are interpreted as CJS. You can rename a file with the `.mjs` extension to use ESM instead.
+- **Dynamically import Vite:** If you need to keep using CJS, you can dynamically import Vite using `import('vite')` instead. This requires your code to be written in an `async` context, but should still be manageable as Vite's API is mostly asynchronous.
+
+If you're unsure where the warning is coming from, you can run your script with the `VITE_CJS_TRACE=true` flag to log the stack trace:
+
+```bash
+VITE_CJS_TRACE=true vite dev
+```
+
+If you'd like to temporarily ignore the warning, you can run your script with the `VITE_CJS_IGNORE_WARNING=true` flag:
+
+```bash
+VITE_CJS_IGNORE_WARNING=true vite dev
+```
+
 ## CLI
 
 ### `Error: Cannot find module 'C:\foo\bar&baz\vite\bin\vite.js'`

packages/vite/index.cjs

@@ -1,5 +1,7 @@
 /* eslint-disable no-restricted-globals */
 
+warnCjsUsage()
+
 // type utils
 module.exports.defineConfig = (config) => config
 
@@ -32,3 +34,15 @@ unsupportedCJS.forEach((name) => {
     )
   }
 })
+
+function warnCjsUsage() {
+  if (process.env.VITE_CJS_IGNORE_WARNING) return
+  globalThis.__vite_cjs_skip_clear_screen = true
+  const yellow = (str) => `\u001b[33m${str}\u001b[39m`
+  const log = process.env.VITE_CJS_TRACE ? console.trace : console.warn
+  log(
+    yellow(
+      `The CJS build of Vite's Node API is deprecated. See https://vitejs.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated for more details.`,
+    ),
+  )
+}

packages/vite/index.d.cts

@@ -0,0 +1,6 @@
+/**
+ * @deprecated The CJS build of Vite's Node API is deprecated. See https://vitejs.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated for more details.
+ */
+declare const module: any
+
+export = module

packages/vite/package.json

@@ -20,9 +20,14 @@
   "types": "./dist/node/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/node/index.d.ts",
-      "import": "./dist/node/index.js",
-      "require": "./index.cjs"
+      "import": {
+        "types": "./dist/node/index.d.ts",
+        "default": "./dist/node/index.js"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./index.cjs"
+      }
     },
     "./client": {
       "types": "./client.d.ts"
@@ -38,6 +43,7 @@
     "dist",
     "client.d.ts",
     "index.cjs",
+    "index.d.cts",
     "types"
   ],
   "engines": {

packages/vite/src/node/cli.ts

@@ -185,7 +185,11 @@ cli
         `\n  ${colors.green(
           `${colors.bold('VITE')} v${VERSION}`,
         )}  ${startupDurationString}\n`,
-        { clear: !server.config.logger.hasWarned },
+        {
+          clear:
+            !server.config.logger.hasWarned &&
+            !(globalThis as any).__vite_cjs_skip_clear_screen,
+        },
       )
 
       server.printUrls()

vitest.config.e2e.ts

@@ -21,7 +21,11 @@ export default defineConfig({
       moduleDirectories: ['node_modules', 'packages'],
     },
     onConsoleLog(log) {
-      if (log.match(/experimental|jit engine|emitted file|tailwind/i))
+      if (
+        log.match(
+          /experimental|jit engine|emitted file|tailwind|The CJS build of Vite/i,
+        )
+      )
         return false
     },
   },