Moving Vite's Node API as ESM only

[bluwy]

Idea

The "vite" package will only export ESM code:

// ✅ Works
import { ... } from "vite"

// ✅ Works
const { ... } = await import("vite")

// ❌ Will not work
const { ... } = require("vite")

Nothing else regarding ESM and CJS is changed in this proposal. Only Vite's Node API as shown above. (Example change branch)

Motivation

1. Continue Vite's push for an ESM ecosystem (philosophy)
2. Simplify internal CJS-specific maintenance
3. Reduced package size
4. Fix CJS types export

Migration path

1. Consumers of Vite will need to consume it in one of three ways:
   1. Add "type": "module" to package.json
   2. Use the .mjs or .mts extension
   3. Use a dynamic import await import('vite')
2. Users who convert to ESM (options i. and ii. above) will need to use assert { type: 'json' } or createRequire() for reading any .json files and define __dirname in any files where it's used
3. If needed, publish a vite-cjs package that users can easily use in npm's "overrides" field.

Research

I've made a poll on Twitter and Mastodon to get a first-pass of what some Vite users think of this:

• Twitter: 89.8% of 1736 votes are fine with this change
• Mastodon: 94% of 149 votes are fine with this change

GitHub search of projects using require("vite") today: search link

Some reasons against this change collected:

1. We're making it harder for existing CJS users.
2. Migrating heavy CJS projects to Vite is harder.
3. While CJS can import("vite") to workaround this, CJS lacks top-level await, making this workaround tricky in cases.
4. Frameworks built on Vite may not be ready. Some status (correct me if I'm wrong):

• ✅ SvelteKit
• ✅ Nuxt
• ✅ Astro
• ✅ Vitest
• ✅ Marko
• ✅ Qwik
• ✅ PreviewJS
• ✅ Ladle
• ✅ Histoire
• ✅ Iles
• ✅ Electron + Vite - Authors are fine with this change
• ✅ SolidStart
• ✅ Angular CLI - done in refactor(@angular-devkit/build-angular): prepare for Vite 5 angular/angular-cli#25634
• ✅ @playwright/experimental-ct-core - done in chore: prefer import over require microsoft/playwright#24568
• ✅ VitePress - done in chore(build)!: drop cjs api vuejs/vitepress#2737
• ✅ Nx - done in feat(testing): Vite 5 compatibility nrwl/nx#18535
• ✅ Laravel + Vite - old laravel projects use ESM syntax in Vite config files interpreted as CJS (.js files without "type": "module"). going to need those users to migrate to a valid setup, but we can do that as part of Vite 5 ([1.0] Drop CJS build and export types first laravel/vite-plugin#235)
• ✅ Storybook - Storybook will dynamically import Vite as part of Storybook 8 later this year (Vite: Support Vite 5 storybookjs/storybook#24395). Users wanting to upgrade to Vite 5 should upgrade to Storybook 8 as well
• ⚠️ Eleventy - PR pending in Dynamically import Vite 11ty/eleventy-plugin-vite#40
• ⚠️ AnalogJS - vite-plugin-nitro, vite-plugin-angular, and platform could be converted to esm (build: convert commonjs packages to esm analogjs/analog#598). nx-plugin needs to stay cjs but doesn't really use vite - only instantiates templates using it. Other packages and user code are already ESM only

✅: Unaffected
⚠️: Changes needed

Feedback

Let us know what do you think of this change. It is still undecided if this will land in the next major version of Vite.

[MrFoxPro]

It would be nice to add feature to disable internal transpilation of config file and let user to run through deno/node+swc/bun

[bluwy]

There's a small discussion about that at #13901 (comment) and #10570 (comment). We usually try to prevent adding new options so we need to pick on one behaviour here.

Personally, I'd like to simply load the config through import() so deno/node/bun handles the transpilation, but that loses TS support for certain cases.

[jaysoo]

Nx will not work with ESM, as we publish as CJS. In order to support this change we'd have to:

1. Also publish Nx as ESM, which will break a lot of tooling.
2. Avoid the Vite Node API -- maybe just invoke the CLI?

There is no plan for us to move Nx to ESM at this point since there is no benefit IMO.

[patak-dev]

You don't need to publish Nx as ESM, but you'll need to consume Vite API using dynamic import from CJS. We need to push for ESM adoption and at one point to complete the migration from CJS to ESM, maintaining support for both takes a lot of work. A lot of the projects on the list above are already ESM only.

I see three places where require('vite') is used in the Nx repo:

• In the docs are using const { mergeConfig } = require('vite')
  https://nx.dev/packages/storybook/documents/custom-builder-configs
• In some of the tests (and it is only to get mergeConfig too)
• On a plugin for cypress there is a call to build that could be replaced by a dynamic import: https://github.com/nrwl/nx/blob/3c13d291dfe1762e6eaf3cef8d6d32dc342d7763/packages/cypress/src/plugins/preprocessor-vite.ts#L77

Do you have some pointers to other places where you are using the Vite Node API so we better understand how this potential change would affect you? Seeing that mergeConfig is recommended in this way we may need to keep supporting it in CJS (as it is the idea with defineConfig)

[jaysoo]

No, we just have the two integration points. We do the same with Vitest now (wrapping with import) so we could do that pre-emptively to ensure things keep working.

[benmccann]

I've migrated that documentation page: nrwl/nx#18380. It documented usage of Storybook, which uses ESM by default, and so is better for users to have documented as ESM anyway

[benmccann]

@jaysoo I sent a PR for the cypress plugin as well, but it had a number of test failures: nrwl/nx#18403. I see there are 8 "agents" and half passed and half failed. I don't know if these are running different sets of tests or the same tests a number of times and this is just demonstrating flakiness unrelated to the change. I'm not really sure where to go from here and might just close the PR and leave it to you, but thought I'd mention in case you had any ideas of something I'm doing obviously wrong. It seems like it should be a simple 1-line change, but I guess I should know better than to call anything simple 😆

[benmccann]

@jaysoo I was able to get the PR for the cypress plugin to pass. It seems it was merely a test flake earlier. Would you be able to take a look? nrwl/nx#18403

[yyx990803]

My thoughts:

1. The migration path isn't great. There are way too many require('vite') usage in the wild, typically at the top of a module. Rewriting these to await import('vite') is non-trivial since you can use top-level-await in CJS. So moving to dynamic import involves restructuring every file, and the entire require chain that relies on those files to be async. The impact is much bigger than "just use dynamic import".

2. When it comes to pushing for ESM, we have to differentiate between "starting with ESM only" vs "switching to ESM only". We had the opportunity to do that when Vite just started as a blank slate. The situation is a lot different now with a lot of existing CJS usage. One thing I learned from the Vue 2 to 3 migration is that you really want to "keep things working" while introducing big changes - if we move to ESM-only in a major, my prediction is that many of the CJS-reliant projects stuck on the previous version for a very very long time because the incentive is just strong enough.

3. Motivation 2/3 are all for Vite's own maintenance convenience; it would obviously be ideal to stop having to worry about them at some point, but users really don't care about it. At the moment, the CJS-proxying-to-ESM approach also seems to incur minimal overhead in terms of package size. CJS type export is something that should be fixed, but again it doesn't really affect users that much.

Overall, I think the biggest problem with this proposal is that the incentives (for users) do not justify the migration cost / negative impact of the change, at least for now. Or, we need to consider a more gentle approach of how to get there.

[benmccann]

A warning for Vite 5 sounds like a good idea to me. And we should still be proactive on helping frameworks migrate to ESM so that their users don't see the warning

[benmccann]

I've spent the past 24 hours investigating this, sending PRs to projects, and trying to figure out which will be hard or easy to migrate. The situation is actually better than I thought at first. The only thing I've found that looks really hard to migrate is @11ty/eleventy-plugin-vite, but it has so little usage that I'm not sure we should concern ourselves with it. While 3.3k files sounds like a lot those migrations look overwhelmingly easy. The biggest category is vite.config.js and .storybook/main.js files both of which can simply be converted to .mjs files since Vite and Storybook both support ESM configs like most tools out there these days. For end users, almost all interaction with Vite is going to be through a framework and config file. That means they'll just need to update to the latest version of their framework and switch their config file to ESM if it's not already. It's not a very big ask and it doesn't sound to me like it'd be terrible to jump straight to ESM. The warning option isn't bad either, but may actually be less clear. We can print a warning, but it might be hard to show exactly where it's coming from whereas an error will give you a stack trace which makes it pretty easy to know where it's coming from

[benmccann]

I took another look at @11ty/eleventy-plugin-vite and it was actually pretty easy to migrate. I sent a PR for it. At this point we're well on our way towards having all the frameworks migrated

[benmccann]

All frameworks now have PRs out. And only three of them are still in review and not yet merged

[nodegin]

I'm using Nestjs with Vite, deprecating CJS means I will need to move back to Webpack or something in the future when Vite v6 comes out.

[benmccann]

For the frameworks above, SolidStart is not ready and Playwright should be added to the list as also not ready.

[benmccann]

Btw, I'm not sure the difference between grey check and green check above

[bluwy]

Hero we don't deserve 🙏

[bluwy]

Btw, I'm not sure the difference between grey check and green check above

I don't know why but GitHub change it by itself somehow. Whenever I tried to "fix" it it doesn't see the change. I don't see a grey check but only oddly various sizes of checks

Screenshot

Not sure how to fix it, but feel free to edit it. (But yeah they have the same meaning)

[benmccann]

@bluwy I've linked to PRs / issues for basically all of the projects above. I couldn't find where Angular uses Vite though. Do you have any pointers as to what that bullet is referring to?

[bluwy]

I found it here: https://github.com/angular/angular-cli/blob/main/packages/angular_devkit/build_angular/src/builders/dev-server/vite-server.ts

[leonheess]

How does that work if you use a TypeScript-based vite config like vite.config.ts?

[bluwy]

https://vitejs.dev/guide/migration.html#deprecate-cjs-node-api should also cover what you need to do with TypeScript. It's similar to in JS.

[leonheess]

If I add "type": "module" I end up with:

failed to load config from ..\mbos-portal\packages\components\vite.config.ts
error when starting dev server:

[bluwy]

Perhaps we are accidentally swallowing the errors. You can try patching this code:

vite/packages/vite/src/node/cli.ts

Lines 224 to 229 in 3e42611

	const logger = createLogger(options.logLevel)
	logger.error(colors.red(`error when starting dev server:\n${e.stack}`), {
	error: e,
	})
	stopProfiler(logger.info)
	process.exit(1)

And log the error manually if it helps continue debugging this. Perhaps instead of e.stack, it should be e.message. If you can figure this out, a PR is appreciated!

[leonheess]

@bluwy to be honest, after raising multiple PRs which never even got a review I have given up on that

[satanshiro]

I am using vite on a nest project i was able to fully migrate a jest monorepo and we are very happy with vitest, we started getting this warning and i wanna be ready for when things might stop working as all the code we have is still in cjs. when you mean change to mts do you mean only the test files? the config file too and setup and environment files? or do you mean the whole project needs to be in esm? is there a way to run the esm build of vitest but the main project stays on cjs?

[benmccann]

It's only Vite's own code that was converted to ESM. Your project's code typically does not need to change as a result of this change. You will just have to ensure that Vite is imported from an ESM file or with await import and not require if including it in a CJS file

[satanshiro]

ok so every file that has a vite import should change to mts/mjs or have an await import (probably mts is faster)

[AdielCohen]

I created new project with vite + REACT+ Typescript SWC
And I got two responses from terminal:

1. "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."
2. "While this integration is maintained by Googlers it is not a supported Firebase product.
   Issues filed on GitHub will be addressed on a best-effort basis by maintainers and other community members."

How do I handle it?
I have already changed the name of the file to vite.config.mjs

[bluwy]

I don't see the issue when using create-vite. Are you using a different template?

[AdielCohen]

No, I used this way:
"npm create vite@latest"
And after that, I did deploy with Firebase

[benmccann]

There's an issue for this in the Firebase repository: firebase/firebase-tools#6652

[alphaoumardev]

I'm currently having the same warning from the terminal

"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."

[benmccann]

That's not enough info to reproduce. There are a million ways to create Vite projects and we don't know what's in yours

[alexander-lysenko]

Have you added "type": "module", into package.json? This worked for me

[alphaoumardev]

I just rename the postcss.config.js to .cjs and add "type": "module" into package.json then works fine the warning disappears.

[if1eight0sty]

@alphaoumardev do we need to change the vite.config.ts to follow ESM syntax?

[alphaoumardev]

Yes!

[andoniabedul]

Hello, giving my opinion here:

We integrated Vite a couple of years ago into a practically legacy project since it has been in operation for almost 8 years, and everything is fine, but we have many boot files and just thinking about having to change the boot chain to an asynchronous mode gives me a headache ; because of course, changing all the requirements of a project to imports is unthinkable... By the way, our project is in a private repository and I think many people will be the same, it cannot be assumed that CJS is not used because the search on Github does not gives you results or because the shiny new frameworks don't use CJS.

So I think I'll stay on Vite 5 for a while (with this lovely warning), until we create a new project from scratch using ESM. I understand your reasons for wanting to make ESM mandatory but I also think that backwards compatibility is important.

[alphaoumardev]

@nodegin so how can we upgrade that? by creating a new vite project or ?

[nodegin]

@alphaoumardev I think so yes, rewriting your existing project with latest tech stack is always the best solution

[bluwy]

You don't need to start from scratch. https://vitejs.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated has some suggestions to migrate over. The easiest step would be the Dynamically import Vite section, or using vite.config.mjs or vite.config.mts. That way you don't have to migrate everything over to ESM. Of course if you have the bandwidth to do a full ESM conversion, that would still be best so the ecosystem can break away from the ESM/CJS dilemma.

[lunelson]

FWIW I am still getting the warning about deprecation, despite my project using vite.config.mts and vitest.config.mts. I can't change my package type property to "module" because it's a Next.js project, and I can't find any other way to make the warning stop... what am I missing?

[revmischa]

I also am using vitest with NextJS, so I am forced to use CJS. Will vitest 6 not be compatible with NextJS projects?

[Dagge11]

Can't you just leave us alone and let us work without infinite mostly useless changes. ESM way of importing modules in Node doesn't work with all modules, EJS way has to be used instead. This JS environment has becoming a nightmare, not because jS is not good (it is) but because those entitled to constantly reinvent the wheel without proper reason.