Rethink dev/prod/mode handling

[bluwy]

Partially implemented in #10996

---

There are a few complications with how these vars interact with each other:

• import.meta.env.DEV
• import.meta.env.PROD
• mode
• process.env.NODE_ENV

Problem

1. When calling resolveConfig it sets process.env.NODE_ENV if mode is production, this could be unexpected when running the dev server, build, or both, in parallel or sequentially.

Idea: Avoid setting process.env.NODE_ENV in resolveConfig. Set it elsewhere (continued below).

---

2. Extending no1, we cannot decide if the app is building for development or production until .env is loaded, because plugins can change envDir & mode in the config hook. However this cause a second issue since some plugins need to know either development or production before the config hook. (e.g. @vue/compiler-*)

Idea: Let the user set process.env.NODE_ENV themselves. If undefined, auto-set development in vite dev, production in vite build (regardless of mode) in the CLI (or createServer / build?)

Also remove the NODE_ENV configuration in .env files as it's unused.

---

3. When building with a custom mode other than production, Vite builds for development, which may not be a good fallback. (Though this is documented)

Idea: Relying on idea no2 which should solve this, also set import.meta.env.DEV = process.env.NODE_ENV !== 'production' and import.meta.env.PROD = process.env.NODE_ENV == 'production' instead.

Others

1. Perhaps we should expose import.meta.env.COMMAND if users want to differentiate between that specifically.
2. May want to introduce command === 'preview' when calling vite preview

Related issues

• import.meta.env.DEV and PROD are incorrect if a custom mode is provided programmatically #9203 (comment)
• fix: prevent production node_env in serve #9066
• fix: reset NODE_ENV on production build end #9058

[Rich-Harris]

If introducing command === 'preview' for vite preview, I'd suggest changing command === 'serve' to command === 'dev' for vite dev, so that command reflects vite [command] in all cases

[patak-cat]

We wanted to do this once we moved Vite to follow SvelteKit on the dev command naming. We didn't because plugins in the ecosystem will break. But I agree it is a pill we should take at some point. I don't see an easy way to deprecate the 'serve' value during Vite 3. If we are going to add 'preview' then we can no longer use command !== 'build', something that I have seen used.
So probably we need to do the change during the Vite 4 beta and then talk directly with plugin maintainers to update their code (especially for the command !== 'build' that won't get a type issue). They could use a helper and check Vite version if they plan to support both Vite 3 and Vite 4 moving forward.

[benmccann]

I agree with all three of your Problem ideas and your two Others ideas (assuming Rich's clarification) with the one caveat:

In Problems #3, when you say "build for development", I'm assuming you mean set import.meta.env.DEV. This variable is inherently unclear as we have two different dev concepts: dev command and dev mode. If you run vite dev --mode=production, vite build --mode=development, vite dev --mode=qa, vite dev --mode=prod-test, vite dev --mode=dev-test it's not exactly clear to me what you want the value of import.meta.env.DEV to be in all those cases. Whether you choose mode or command, some of those cases end up being pretty weird. The ideal behavior has caused a lot of disagreement amongst the Svelte team. Probably the best solution would be to avoid using "dev" in both contexts. Some ideas on that:

• I don't think that import.meta.env.PROD should be whether the build command is being used since the word prod would be used only in mode. Instead we should have import.meta.env.BUILD to reflect the command
• We could replace dev mode with local mode to avoid overloading the term dev
• We could just kill the import.meta.env.DEV variable. Users could do !import.meta.env.BUILD (command) or !import.meta.env.PROD (mode) and/or we could introduce import.meta.env.DEV_CMD and import.meta.env.DEV_MODE. Users who miss import.meta.env.DEV could define it in a manner of their choosing.

[benmccann]

we would have set process.env.NODE_ENV to something... Perhaps this would be easier to work with?

We wouldn't have set it to anything, right? Only user would, if I understand correctly. And so it would always be 'development' unless they explicitly change it. I think that's harder in some ways because it requires them to set an environment variable to make it work

Re import.meta.env.BUILD, perhaps import.meta.env.COMMAND covers that.

It would just be a shortcut so you don't have to do import.meta.env.COMMAND === 'build'

[bluwy]

We wouldn't have set it to anything, right? Only user would, if I understand correctly. And so it would always be 'development' unless they explicitly change it. I think that's harder in some ways because it requires them to set an environment variable to make it work

We would set process.env.NODE_ENV if it's undefined per idea no2:

If undefined, auto-set development in vite dev, production in vite build (regardless of mode) in the CLI (or createServer / build?)

If the user does set it manually, then we'd respect that (except probably in dev where production is not possible).

We would always need to set to some value so that dev and build works as expected by default. But this would have to be noted clearly in the docs so the side-effects are clear.

[benmccann]

Ok, so summarizing, here's the proposal:

• Introduce command === 'preview' for vite preview and change command === 'serve' to command === 'dev' for vite dev
• Let the user set process.env.NODE_ENV themselves. If undefined, Vite will set it to development in vite dev and production in vite build (regardless of mode)
• Set import.meta.env.DEV = process.env.NODE_ENV !== 'production' and import.meta.env.PROD = process.env.NODE_ENV == 'production'

These largely sound like good changes to me. I still have a bit of concern that mode and NODE_ENV are fairly duplicative concepts (they're exactly equal by default) and so are ripe for confusion. Maybe we could make mode use the values local and build by default to separate the concepts a bit?

[bluwy]

Yep the 3 points sounds right to me 👍 About mode it does look like this proposal reduces it's use, but we might still want to keep it as-is for the concept of "staging" builds etc. So they have "development", "production", "staging" modes and use the .env.{mode} naming scheme.

[benmccann]

Another option might be to make mode be undefined by default and only set it when the user provides some value

[zhaoterryy]

Just got hit by this problem, took quite a while to find this discussion.

Running vite build with the following config results in import.meta.env.PROD === true.

vite.config.ts:

export default {
  mode: 'development'
}

Running vite build --mode development results in the same thing.

This behavior change from vite v2 from vite v3 is undocumented afaik. In fact, the unexpected behavior contradicts the documentation here: https://vitejs.dev/config/shared-options.html#mode.

Are there any options to do a build with import.meta.env.PROD === false?

[bluwy]

I can't reproduce this, are you setting process.env.NODE_ENV somewhere in your config?

[jsejcksn]

@bluwy I can also reproduce this — here's a link:

https://stackblitz.com/edit/vitejs-vite-netggr?file=dist/assets/index-5e52de89.js

Have I misunderstood something or this still a bug?

mode is set to 'development' on line 7 of vite.config.ts:

export default defineConfig({
  plugins: [react()],
  mode: 'development',
});

On line 6 of src/main.tsx:

console.log(import.meta.env);

In the terminal, use the build command:

vite build
# OR
vite build --mode=development

Near the end of line 40 of the JS bundle:

dist/assets/index-5e52de89.js:

console.log({BASE_URL:"/",MODE:"development",DEV:!1,PROD:!0,SSR:!1})
//                                               ^false  ^true

[bluwy]

@jsejcksn that's expected as mode only defines kind-of the "name" of the build, it doesn't change the build environment. If you want to build in a development environment, you can create .env.development with:

NODE_ENV=development

so Vite will build it in development env. This may seem weird at first, but we found over time that automatically inferring the env often catches people off guard too.

[jsejcksn]

@bluwy Thanks for the reply with the information.

that's expected as mode only defines kind-of the "name" of the build, it doesn't change the build environment.

If this is documented somewhere, I did not see it — I saw the note about env vars at the end of the Library Mode section, and this note at the end of the Modes section

As vite build runs a production build by default, you can also change this and run a development build by using a different mode and .env file configuration:

# .env.testing
NODE_ENV=development

But IMO it does not clarify what you detailed.

Have I missed something else? This might be an opportunity to improve the documentation and better explain to users that Vite's "mode" is a distinct/unrelated concept in comparison with the environment variable NODE_ENV that is potentially used by the template framework. For example:

In my current case, I wanted to run a build in development mode so that the development version of React is what went into my bundle — I'm developing a Chrome extension with Vite and, AFAICT, there's no way for me to test my extension using the dev server because of the way that Chrome only runs extensions (with the granted privileges) from chrome: URLs, so I have to perform builds in dev mode and test the unpacked extension directory.

[bluwy]

It is documented if you replace the "testing" example in the docs to "development". But feel free to open a PR if there's part you see can be made clearer. FWIW there used to be a line that mentioned mode isn't just dev/prod at https://github.com/vitejs/vite/pull/11045/files#diff-7286887bcd9afe25bd2e21bde2594bd9d6afc0a8c55b9ad2853161a895e91c85L123, but it was changed as it doesn't flow well.