From 404f30f5a4f9d5ad8ac683fb8cd7adc87d308675 Mon Sep 17 00:00:00 2001 From: Bjorn Lu Date: Thu, 21 Sep 2023 17:01:16 +0800 Subject: [PATCH] feat!: deprecate cjs node api (#14278) --- docs/guide/troubleshooting.md | 29 +++++++++++++++++++++++++++++ packages/vite/index.cjs | 14 ++++++++++++++ packages/vite/index.d.cts | 6 ++++++ packages/vite/package.json | 12 +++++++++--- packages/vite/src/node/cli.ts | 6 +++++- vitest.config.e2e.ts | 6 +++++- 6 files changed, 68 insertions(+), 5 deletions(-) create mode 100644 packages/vite/index.d.cts diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md index e5bfd3869fb647..ca6628b5798ca8 100644 --- a/docs/guide/troubleshooting.md +++ b/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'` diff --git a/packages/vite/index.cjs b/packages/vite/index.cjs index 133ce6b05ded69..7132d113b0540a 100644 --- a/packages/vite/index.cjs +++ b/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.`, + ), + ) +} diff --git a/packages/vite/index.d.cts b/packages/vite/index.d.cts new file mode 100644 index 00000000000000..146c8bc289e518 --- /dev/null +++ b/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 diff --git a/packages/vite/package.json b/packages/vite/package.json index 7dbbb4b0b7f191..0bfea1fb222601 100644 --- a/packages/vite/package.json +++ b/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": { diff --git a/packages/vite/src/node/cli.ts b/packages/vite/src/node/cli.ts index fa380dd06ee8f5..80b237d7c00814 100644 --- a/packages/vite/src/node/cli.ts +++ b/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() diff --git a/vitest.config.e2e.ts b/vitest.config.e2e.ts index fa0d76f1cd508d..af1b358deb87f6 100644 --- a/vitest.config.e2e.ts +++ b/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 }, },