I don't really have an opinion if we have to change them as a list or not. Accessing the list of environments is not common I think, usually framework or plugin authors already know what environment they want to work on, so as long as we keep or improve the DX of accessing environments (rather than iterating them), I'm fine with it.

I think the $ convention makes it easier to work with environment configs; I never liked the deep structure we have right now (root->environments->name->resolve->alias).

I don't have a strong opinion on whether we should switch .environments to an array if we go with a $ convention. Personally, I don't see a lot of benefit in that. Objects can be iterated.

Making every new top level key a breaking change doesn't sound like a good idea in the long term.

I agree with this. Also I think having environments in top-level is kind a confusing.

export default defineConfig({
 server: {},
 build: {},
 ssr: {},
 edge: {}
})

This is requires the users to understand which key is a not an environment to know what option can be set (you can use your IDE's help but there's a mental overhead IHMO).

Additionally, I think the types are difficult to write.

interface UserConfig {
 [key: string]: { resolve?: { alias?: Record<string, string> } }
 root?: string
}

This declaration errors. We need to keep UserConfig as an interface for vitest, so I don't know if we can solve this.

I like the $environment pattern. It feels cleaner than environments.environment. You can understand that the key is an environment easily and the types can be written easily. The following declaration does not error.

interface UserConfig {
 [key: `$${string}`]: { resolve?: { alias?: Record<string, string> } }
 root?: string
}

This is requires the users to understand which key is a not an environment to know what option can be set (you can use your IDE's help but there's a mental overhead IHMO).

Good point. I think I'm persuaded more to use $ to denote an environment now.

Additionally, I think the types are difficult to write.

I don't really expect us to type out the environments ourselves. I'd expect plugin or framework authors to know that they're working on a specific environment to extend the types manually like the Vitest example (but probably different like showed in the proposal's Vite config & environment API types section).

The proposal from this thread is implemented here

• refactor: dollar sign prefixed environments #18426

Let's see a concrete case. You introduced the warmup feature and went with this API:

server: { warmup: { clientFiles: [], ssrFiles: [] }}

You would like to change this to (let's discuss only the defaults vs mixed here):

dev: { warmup: { files: [] }}, // client-only
$ssr: { dev: { warmup: { files: [] }},

I agree this looks good. I actually did this at first for all config options. Every environment specific option on the top level was client only. We had to revert this and go with the current design because resolve, build, and almost every top level key is shared. So this was a breaking change. So, one part of our disagreement is that I'm putting more value on consistency. It is hard to accept for me that we want to have mixed defaults and client-only top level keys when we would only want to make client-only 2-3 of all the config options in Vite (that are a lot). If we would be talking about half the keys, I would understand, but this is a tiny fraction of them.

About not having two ways of setting things for the client. For every top level key that act as a default (most of them), if a plugin or user wants to be sure that it only affects the client, being able to use $client is a great feature that we currently don't have (or we have during build if they use !isSsrBuild). If we don't offer this, then every time they need to set something for the client only, they will need to set the default value and then force a different value for all other environments. It may not even be possible to do it right. For users, they don't know all the environments. For plugins, they may not know at that point. And even if you know, what value do you use? Should you set it to the default? Do we need something like the 'unset' CSS value?

As a note: Every time we decide that a shared top level key will now be able to be configured per-environment (for example, resolve.alias), with the current design, we can just move it to EnvironmentOptions and we don't break anything. It was already working like if it was a default for all environments. The only diff is that now you can override it per environment. This also works if we have mixed, but we would need to move to it as a default and not client-only.

I think I'm lost in the discussion. Is your opinion "the currrent behavior of deriving (mostly) all the values of the root options to all the environment is not good from a gradual adoption point of view"? In that case, would you expand on that part? Is it the point that when migrating to CSR+SSR from CSR only, that users need to move all options under $client?

As a summary of what I understand from this thread, in case it is useful. Bjorn's proposal:

• client is configured at top level (there is no $client, you can only set its config through top level)
• there is a special ssr top key.
• you configure the other environments through $env.
• for each non-client environment, some props from top level are taken as default, some are not.

Current design (if we use the $ prefix):

• defaults are configured at top level
• the special ssr top key is going to be removed
• you configure environments using $env (and there is a $client env by default)
• for all environments, all top level props are taken as default

Yeah @patak-dev is spot on with the summary 👍

For every top level key that act as a default (most of them), if a plugin or user wants to be sure that it only affects the client, being able to use $client is a great feature that we currently don't have

I agree with this. I feel like there's a tradeoff between "DX for users who only edit vite.config.js" and "DX for plugin/framework authors" between both our discussions. I don't think there's a right decision here and it depends on who we favor more, which right now is the latter.

I don't really have a solid idea to support my proposal with it at the moment, other than tossing back, do people really need to set a config for the client only? Given how far we've already come without that? 😄

@bluwy shared a set of props that will be a footgun if shared between client and server:

• resolve.conditions
• dev.optimizeDeps.include, dev.optimizeDeps.exclude (maybe the whole dev.optimizeDeps?)
• dev.warmup

Even if I pushed back in this thread, if we believe that these props will become a footgun, then we may not have an option but to break the consistency. Maybe one way to see it that would still go with the current design is that we have certain exceptions (well marked in the docs) for props that don't work as default for both client and server environments
We could even still consider them as defaults, but that only apply to consumer: 'client' environments (where they would make sense in general).
Something I dislike about this is that then we have no way to set a default for all server environments for these, but it may be something we need to live with (and if server environments are generally different runtimes, node and workerd for example, then a default for these is not really needed)

I didn't get to this yet as it was unrelated to the other bits in the proposal. I don't think an environment should stop users from configuring things like resolve.conditions. But with the current proposal, that is possible, and I think in a cleaner way:

Wouldn't plugins still be able to change the values in config.$edge? (By "current proposal" I assume the current implementation with the $env idea)

This also works fine right now

They don't take part in config merging, or allow plugins to set them though.

Ah, yes, this is true. In your proposal, you'll have the same issue if plugins are the ones adding the environments instead of the user. Or do you plan to restrict that environments need to be defined upfront? In the current implementation, because there is a well defined set of per-environment options, the user can still do overrides if needed (similar to how a user can set ssr.xxx values now). Plugins can also know and modify this common set of values.

About extending the environment config. I see the value in plugins being able to change them. Right now, they would be able to do it using configureServer. Maybe we could modify configEnvironment(name, options) so options also include extra options added by the environment? This hook is called once we know the environment type. I don't know if this is possible though.
Another issue I see is that this is promoting polluting the environment options object, and we may end up breaking frameworks and libraries lately. So maybe these options should be in another object or under a custom key.

It would be good to have a concrete use case for a plugin needed to change an option from an environment. One of the guiding principles of the current design is to push for fine grained options so plugins can be environment agnostic. This goes against this idea.

Or do you plan to restrict that environments need to be defined upfront?

They don't need to be defined upfront. The config.environments: {} and config.$env can be separate and could be validated to match after resolved.

Another issue I see is that this is promoting polluting the environment options object, and we may end up breaking frameworks and libraries lately. So maybe these options should be in another object or under a custom key.

Yeah it might be better to encourage as a separate object instead. The idea of the proposal is that the environment libraries define what the config shape should look like, so they can construct any option shape they like. Extending the environment options would be a risk if they want to do so.

It would be good to have a concrete use case for a plugin needed to change an option from an environment.

I guess I don't have a real-world usecase, but was thinking that environment libraries can take part and extend the Vite config (e.g. through config.$edge) and fit nicely with how the entire Vite config generally works. They don't have to all be the same set of environment options.

What if it's both? The proposal is to have dispatchFetch even on the ssr environment alongside the import method. Maybe it's better to expose an actual Environment type there instead of using a string?

If it's both it could use a | union perhaps, but I feel that this isn't common in practice. Exposing an Environment type is fine by me too. The string is mostly a placeholder and we could extend it out.

In both cases, the ViteEnvironments type should also actually be a ViteDevEnvironments type.

I don't think we need to narrow that down though. Isn't the config or resolvedConfig not part of dev? The types could possibly extend for more than only dev.

Another thing is this.environment - how do you type it?

Good point. We still need a type guard, but perhaps combining with the ambient types above, they can typeguard to a more stricter type?

I am also not sure if frameworks actually access environments directly on the server. Wouldn't you use some kind of generic adapter that doesn't care about this?

This is something I've wondered about and I feel like the push for plugins to check "this is a general server environment" rather than "this is an ssr-node environment" isn't going to work out at the end. There will be a lot of permutations of general server environments, not only between environment configurations but also different framework's intention of "what this environment is used for", that eventually it'll have to lead to hardcoding a specific environment.

AFAIU we're adding properties like consumer and webCompatible to define these characteristics, but I don't know if it'll scale well.

With the $env proposal, can you access server.$ssr/server.$client environments?

I guess you can! That's mostly @patak-dev's idea though which I like

This doesn't make a lot of sense to me. If plugin authors populate the environments option, why would they even use any functions for that? Wouldn't they set options directly in the config hook of the plugin?

The "environments" plugin-like API feels excessive to me

I think these two are related for my answer. I don't think my proposed environment "plugin-API-ish" design is perfect, but I want it to reflect close to the plugin API so it feels similar. Right now it feels like a completely different API.

1. The class-based design, I'm not sure if fits well with the other Vite APIs now. We have classes like ModuleGraph exposed but we never have an API with new Something() (CMIIW).
2. The API is plugging multiple abstractions into one. In DevEnvironmentContext, hot, remoteRunner.transport, and depsOptimizer all looks like abstractions rather than config options. I'm also not sure splitting an environment as DevEnvironment and BuildEnvironment is ideal too, it feels (at least on surface) more abstractions.

My idea is that there's no longer createEnvironment, so you'd create environment instances like Vite plugins, which helps users to familiarise with it, and add them to config.environments: { ... } like plugins. I'm sure there's good reasons why the design is the way it is today and I'd love to hear more certain exploration/challenges you had. If someone asks me why environments look so different and tricky to set up, I'd like to be able to give a good explanation 😅

I am also not sure if frameworks actually access environments directly on the server. Wouldn't you use some kind of generic adapter that doesn't care about this?

This is something I've wondered about and I feel like the push for plugins to check "this is a general server environment" rather than "this is an ssr-node environment" isn't going to work out at the end. There will be a lot of permutations of general server environments, not only between environment configurations but also different framework's intention of "what this environment is used for", that eventually it'll have to lead to hardcoding a specific environment.

AFAIU we're adding properties like consumer and webCompatible to define these characteristics, but I don't know if it'll scale well.

If the framework wants to allow node or workerd environment, they will declare it like:

declare module 'vite' {
 interface ViteEnvironments {
 worker: {
 type: 'fetchable'
 config: NodeEnvironmentOptions | WorkerdEnvironmentOptions
 resolvedConfig: ResolvedNodeEnvironmentOptions | ResolvedWorkerdEnvironmentOptions
 }
 }
}

Is this what you have in mind?

Yup, and my replying comment at #18415 (reply in thread) elaborates a bit more on it. Where this declaration can happen is entirely up to the consumer, e.g. the framework/library author. Runtime provider authors don't do this as they don't know the env names ahead of time, but they'll export the types primitive to construct this. (Maybe in a less verbose way than what we have in the proposal now)

I think frameworks/plugins guarding them before accessing it should be fine. Similarly in the current implementation for server.environments.* we don't make it nullable to make it easier to use.

Do you mean the type of config.workerd will be something like Record<string, any> & EnvironmentOptions? (= polyfillNode won't be suggested.)

export default defineConfig({
 environments: { /* */ },
 workerd: {
 polyfillNode: true,
 },
})

Maybe this is related to #18415 (reply in thread)

Not exactly I think, here's an example config I'm thinking about:

// vite.config.ts
import { defineConfig } from 'vite'
import framework from 'framework'
// Import the adapter, and the ambient types for `config.$cloudflare` would be augmented
// so you get typings for fields like `config.$cloudflare.polyfillNode`. If the framework is structured
// differently where this import doesn't happen, the end user could add /// <reference types="..." />
// in this config instead
import cloudflareAdapter from 'framework-adapter-cloudflare'
export default defineConfig({
 plugins: [
 framework({ adapter: cloudflareAdapter() })
 ],
 $cloudflare: {
 polyfillNode: true
 }
})

I see. If the framework accepts both vercel and cloudflare, would it be like

export default defineConfig({
 plugins: [
 framework({ adapter: cloudflareAdapter() })
 ],
 $cloudflare: {
 polyfillNode: true
 }
})
// ---
export default defineConfig({
 plugins: [
 framework({ adapter: vercelAdapter() })
 ],
 $vercel: {
 polyfillNode: true
 }
})

or

export default defineConfig({
 plugins: [
 framework({ adapter: cloudflareAdapter() })
 ],
 $edge: {
 polyfillNode: true
 }
})
// ---
export default defineConfig({
 plugins: [
 framework({ adapter: vercelAdapter() })
 ],
 $edge: {
 polyfillNode: true
 }
})

? The latter one is similar to the current design. I'm not sure what the pros and cons is for the former one.

(削除) For the latter one, on the framework side, I guess they will have to do something like below and it's a bit tedious. (削除ここまで)

const framework = ({ adapter }) => {
 return {
 configResolved(config) {
 if (adapter.name === 'cloudflare') {
 const config = (config.$edge as CloudflareOptions)
 // do something
 } else if (adapter.name === 'vercel') {
 const config = (config.$edge as VercelOptions)
 // do something
 }
 }
 }
}

Edit: on second thought, I think this happens with the current design as well, so ignore it.

I think I understand your idea now.

👍 Yeah I think either patterns work and is up to how the framework wants to structure it. If there's only ever one adapter, it might make sense to share the same key, but regardless you'd still get fine-grained types depending on the augmented types provided by the adapter library.