Unclear configuration setup for bundling for non-browser environments

[cpojer]

Describe the bug

I'm using Vite to bundle my backend and it's been working great for multiple years. Yesterday I updated a transitive dependency (ws) which in recent versions introduced the "browser" condition in exports: https://github.com/websockets/ws/blob/master/package.json#L24

With this change to ws, my backend build picked up the browser version instead of the import/require version meant for node. It would be great if Vite could automatically disable the browser condition if the target is set to node*, or if mainFields does not include browser, or if we could align on some way to tell Vite to do a non-browser build and automatically choose the best defaults for conditions, mainFields and other configuration options.

Here are the relevant parts of my Vite setup:

export default defineConfig({
  build: {
    target: 'es2022',
  },
  resolve: {
    mainFields: ['module', 'main'],
  },
});

I changed my build target to node22 without success. I then explored the Vite docs on configuring conditions which says:

The default allowed conditions are: import, module, browser, default, and production/development based on current mode. The resolve.conditions config option allows specifying additional allowed conditions.

This means that there is no direct way to disable the browser condition. From exploring Vite's source, I figured out that adding conditions: ['node'] to the resolve configuration will skip over the browser condition. This is pretty confusing, and hard to piece together unless you have experience with bundlers, module resolution and node.

Note: I couldn't find the place in Vite's source where the default conditions are set. Would appreciate pointers

Reproduction

https://github.com/nkzw-tech/athena-crisis

Steps to reproduce

• Run pnpm install
• Create a file in artemis/ that does import ws from 'ws'
• Add the above Vite config at artemis/vite.config.ts
• Run a Vite build

The resulting bundle will use the browser version of ws instead of the expected node version, unless conditions: ['node'] is passed.

System Info

Not relevant.

Used Package Manager

pnpm

Logs

No response

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Make sure this is a Vite issue and not a framework-specific issue. For example, if it's a Vue SFC related bug, it should likely be reported to vuejs/core instead.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
• The provided reproduction is a minimal reproducible example of the bug.

[bluwy]

Vite's default behaviour isn't meant to build for non-browser environments, except the build.ssr: true config to build for SSR which may also work for your usecase. Otherwise general nodejs support is being discussed at #7821. I'll close this in favor of that.

[cpojer]

The Vite website doesn't mention that Vite is only for browers, and the upcoming Environments API seems to be explicitly about broadening the surface area of where Vite runs in. Would you mind you elaborating and confirming that Vite is not interested in supporting non-browser environments?

I'm not asking to improve the default configuration, I'm merely pointing out an inconsistency in Vite's resolution configuration system that defaults to browser resolution unless multiple specific/magic configuration settings are applied that require reading Vite's source. Further, the issue I outlined is quite different from the original intent of #7821, and closing this issue in favor of the that one, which doesn't mention anything related to resolution, seems to make it likely that it will be forgotten.

I can understand that you may not want to make changes in Vite directly, but it would make sense to at least update the docs, and keep the issue open until you can agree on what guidance you'd like to give to people bundling for non-browser environments.

[patak-dev]

@bluwy lets keep this one open for now with a to-be-discussed label and have it in the Vite 6 milestone. I think this one may be useful when reviewing the configuration side of Environment API, and if we end up relaxing our stance on supporting non-browser environments.

[bluwy]

I think the getting started page is already clear that it's a web/frontend focused build tool. It doesn't mention that it doesn't support non-browser environments, because technically Vite does if you use build.ssr: true, which SSR is part of web tooling.

However, some people (and perhaps this case) don't exactly want SSR, but simply plain nodejs target support without SSR heuristics, which is something Vite doesn't support well now, but we're certainly interested in supporting non-browser environments where Environment API (and vite-node package) comes in.

I don't think we should change the documentation now because development of the Environment API is still in flux.

[bluwy]

@patak-dev we can use #7821 to track that? I don't see why we need two issues. The discussion in that issue is similar to this.

[patak-dev]

I wanted to keep both issues as this talked about resolve conditions and the linked one was about node builtins. Checking the comments in #7821, it seems that has evolved into way more than that. Ok, I'm fine tracking this one as part of that one if you think it is easier to organize. I'll add a comment there pointing to this one and asking for feedback on the Environment API proposal from the folks involved.

[patak-dev]

/rant it is terrible that GitHub uses "not planned" when you close the issue as duplicate.