Alternate Vite Environment API design

[bluwy]

Exploration of a different API design for Vite's environment API and different tradeoffs. In typical fashion, I submit ideas usually too late 😅 So I don't expect that we're integrating or be considering any of these soon.

Goals

• Decrease API surface layer compared to current Environment API
• Additional environment configuration are additive
• Allow better typings for runtime/plugin authors

API design

Vite config

Click to expand

Most Vite users are spending most of the time interacting with the Vite config. It should be additive, approachable, and simple to configure the options.

Vite stays browser-focused, with all top-level options reflecting for browsers first. Some options may be re-used for other environments (like SSR), and some may not make sense for them, which is fine. The environment specific options should be kept under the environment key.

Here's an example without environment API yet (as an exercise to clean up the API to make way for environment API later):

// vite.config.ts

export default {
  build: {
    modulePreload: false,
    outDir: 'dist/client',
    // ssr* options here are all deprecated, moved to `ssr.build.*`
  },
  ssr: {
    // Environment-specific options
    external: [/^node:/],
    noExternal: true,
    // Partial options from top-level options. Not all top-level options
    // can be configured here unless they make sense for SSR. SSR-specific
    // options can also extend the top-level options, like `build.emitAssets`.
    resolve: {},
    build: {
      outDir: 'dist/server',
      emitAssets: false,
    },
  },
}

Vite config with environment API

Click to expand

// vite.config.ts
import { node } from 'vite/environments'
import { workerd } from 'vite-environment-workerd'

export default {
  // Add additional environments to Vite, usually set by plugins.
  // `client` and `ssr` keys are not allowed. Functions are discouraged
  // from accepting parameters, they should receive the config from the
  // top level `rsc` or `workerd` config below. Unless for other reasons
  // like init-only options or fallback config values.
  environments: {
    rsc: node(),
    workerd: workerd(),
  },
  ssr: {
    // ...
  },
  // These environments can be configured here, the types are explained
  // in the next section.
  rsc: {},
  workerd: {
    // workerd-specific options
    polyfillNode: true,
    // Environment-specific options
    external: [/^node:/],
    noExternal: true,
    // Partial options from top-level options. Similarly as explained above.
    // However the environment instance can decide what to allow users to configure.
    optimizeDeps: { include: ['@workerd/workerd'] },
  },
}

Vite config & environment API types

Click to expand

Environment API libraries (from runtime authors) can return a config type that consumers can use. Consumers like framework or plugin authors can add something like this:

import type { NodeEnvironmentOptions } from 'vite/environments'
import type { WorkerdEnvironmentOptions } from 'vite-environment-workerd'

declare module 'vite' {
  interface ViteEnvironments {
    rsc: {
      type: 'runnable'
      config: NodeEnvironmentOptions
      resolvedConfig: ResolvedNodeEnvironmentOptions
    }
    worker: {
      type: 'fetchable'
      config: WorkerdEnvironmentOptions
      resolvedConfig: ResolvedWorkerdEnvironmentOptions
    }
  }
}
// 1. Vite's `UserConfig` will auto-augmented with `rsc: NodeEnvironmentOptions` option.
//    (similar to resolved config)
// 2. `this.environment.rsc` will have stricter types defined here.

// workerd options types could look something like this
interface WorkerdEnvironmentOptions
  extends Omit<EnvironmentOptions, 'consumer' | 'webCompatible'> {
  polyfillNode: boolean
}

interface EnvironmentOptions {
  external?: string[]
  noExternal?: string[] | boolean
  resolve?: ResolvedResolveOptions
  consumer?: 'client' | 'server'
  webCompatible?: boolean
  build?: BaseEnvironmentBuildOptions
  // other allowed configuration
}

The benefit with this approach is that framework or plugin authors can define what they expect to exist and define it themselves. They also get stricter types ootb, for example:

1. They don't have to type-guard whether an environment is runnable or fetchable.
2. They are free to extend or limit certain options from being edited (for framework configs).
3. Environment specific options, e.g. worker polyfillNode, can also be defined in the config.

Create an environment (runtime authors)

Click to expand

An environment instance looks like a plugin with certain properties that act like hooks.

NOTE: I'm not very familiar with the environment requirements, so I might be missing something. As such, the below is also a rough sketch and some hooks may be redundant.

interface Environment<Config = Record<string, any>, ResolvedConfig = Config> {
  name: string

  // Similar to plugin hooks, environments can track when the server/build started and
  // ends. This is useful for caching or cleanups. Not all plugin hooks are inherited.
  buildStart: () => void
  buildEnd: () => void

  // Custom hook to resolve its own config, e.g. like Vite, adding default values, making properties
  // non-optional etc. By default it'll return `config` like a no-op. The resolved config can
  // be access from e.g. `ViteResolvedConfig['workerd']` or `this.environment.workerd.config`.
  configResolve: (
    config: Config,
    viteConfig: ResolvedViteConfig
  ) => ResolvedConfig

  configureServer: (server: ViteDevServer) => void
  configureEnvironment: () => BaseEnvironmentOptions // or `configureBehaviour`?

  fetchModule: (node: EnvironmentModuleNode) => FetchResult
}

// `WorkerdEnvironmentOptions` defined in code example above
function workerd(): Environment<WorkerdEnvironmentOptions> {
  let resolvedConfig: WorkerdEnvironmentOptions
  let miniflare: any

  return {
    name: 'workerd',
    configResolve(config: WorkerdEnvironmentConfig) {
      const resolved = {
        ...config,
        polyfillNode: config.polyfillNode ?? true,
      }
      resolvedConfig = resolved
      return resolved
    },
    configureEnvironment() {
      miniflare = new Miniflare({})

      return {
        external: resolvedConfig.external,
        noExternal: resolvedConfig.noExternal,
        resolve: resolvedConfig.resolve,
        build: resolvedConfig.build,
      }
    },
    fetchModule(node) {
      return miniflare.fetch(node.url)
    },
  }
}

Using en environment (framework & plugin authors)

Click to expand

As showed in Vite config with environment API section, additional environments can be configured by framework or plugin authors by adding to the environments key. If an existing one exists during config merging, it'll error.

In most cases, framework can access via server.environments.ssr.import('...') like before.

For plugin authors, I quite like the current this.environment.<env-name> design. The discussions around per-environment plugin should also be unaffected by this proposal. The only change with this proposal is that configEnvironment is likely not needed anymore as environment instances have the configResolve hook.

Summary

1. Stricter types. Only allow specific environment options to be configured so there's less "generalized options" that we have to introduce, and less commitment to make all work across environments.
2. Environment-specific options are tucked away one-level deep and can be access when needed. If Vite eventually wants to make a pattern first class, the environment key will already be in place similar to ssr and worker options.
3. There should be less abstraction that authors need to understand. If there's common patterns that are required to interact with the API, we can export utility functions.

Caveats or uncovered topics

1. An obvious pitfall is that extended environments occupy top-level config keys. We could namespace them, but I think it defeats the purpose and ease of use.

   I personally don't think it's a big issue as we don't add new top-level options often. We can mark this not covered by semver, but still check the ecosystem if there's certain keys in use that're popular if we need to add a new option.

2. Compatibility with Vitest. Since I worked on frameworks more, my bias here probably won't fit well with how Vitest will integrate. I'm open to extending certain parts of the API to make it work better with Vitest.

   However, I think we should consider frameworks as our main target audience given the ecosystem, and if Vitest need to apply specific hacks or workaround, I think it should be acceptable.

[patak-dev]

Thanks for the writing down the proposal @bluwy! It would be great for others to check things out, maybe even try to implement some of this in a POC as I made deeps mental cliffs now with the other design and it is a bit hard to get out of them and check it as a blank slate. I think there are some things that we seems to agree on here that is good to enumerate again as this is the bulk of what we are introducing in Vite 6 as experimental:

• The flexibility to create as many environments as needed for a single Vite dev server
• The possibility to run the code in a different process through ModuleRunner
• Each environment should be represented as an instance that controls its own module graph and plugins container
• Plugins can access this instance through this.environment

So to guide others, this proposal affects how to configure the environments and an alternative for API for environment instances.

[patak-dev]

About:

An obvious pitfall is that extended environments occupy top-level config keys. We could namespace them, but I think it defeats the purpose and ease of use.

We evaluated this idea and decided that having the environments key to scope new environments was a requirement, mainly because of this pitfall. Making every new top level key a breaking change doesn't sound like a good idea in the long term. This is something that we can discuss independent of the whole proposal (maybe taking bits of the whole idea) and applying them first could be a good way to see where we end up before we need to try to rework the whole thing.

One of the ideas we checked out was using top level keys with a namespace for environments. For example, Nuxt uses top level $environment keys to do environment overrides. If environments.server is really difficult to grok (and I understand that the extra level makes it a hard sell), we could move to:

export default defineConfig({
  $client: { ... },
  $ssr: { ... },
  $edge: { ... },
})

One of the ideas for environments was that the API feels more consistent. You have config.environments.edge and server.environments.edge. If we do this change, maybe we could still have this consistency and have config.$edge/server.$edge but keep server.environments as a way to iterate them.

Note that this could also apply to your proposal. Given a good way to redefine how the current ssr key works.

[bluwy]

I really like the $environment pattern. My thinking without namespacing is that like the ssr option today, it could graduate to a first-class support sharing the same key. But if name clashing is a big concern using $environment is a nice alternative.

Also, I don't think we need to have $client and $ssr. My idea is that the top-level options already apply to client, and ssr key allows you to dig into builtin-SSR handling options. I prefer not to over-expose the concept of environments to end-users (those who ever only interact with vite.config.js).

Re consistency, technically the proposal still preserves config.environments.edge, just that you don't put the configuration there anymore. But overall I'm not sure if we have to preserve the consistency as they don't point to the same values. But server.$edge is interesting and appealing though.

[patak-dev]

If the proposal still preserves config.environments.edge, that is another reason why I would go with marking these as a special value with $ (or similar). I think there is value in having UserConfig and ResolvedConfig map as close as possible, so initially, I would be leaning towards config.$edge/server.$edge but if environments is still there in config, I'm ok with this being a config authoring shortcut only. The $ would make it easier to type too, especially for new default environments (where you wouldn't even need to define them and import node() as in the proposal)

[bluwy]

To be clear, config.environments.edge would exist, but it's like accessing config.plugins[0]. You wouldn't really do that in practice unless you're doing something hacky. To get the options, you'd have to use config.$edge instead.

[patak-dev]

At one point, config.environments and server.environments were lists. We switched to the object form so the config and server instance would match the UserConfig. If we go with $edge and that can be accessed as config.$edge, then IMO we should go back to .environments being a list (it would also make using it simpler in places we are currently doing Object.values()/etc)

[bluwy]

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.

[patak-dev]

About having the top level keys refer to the client environment. We first implemented a similar design. I can't find where we did the switch now in the sea of commits.

I think it is confusing that some top level options are client only, and some of them affect all environments acting as a default. We currently also have a mix of these though, and people are fine with it. If we think that we should have certain top level options configure the client environment only (a good case may be dev.optimizeDeps), we can check this out (again, independent of the rest of the proposal).

We would need to document for each config option if it is client-only or a default for all environments. And this would be orthogonal to the option being shared or per-environment. We also would need to treat these client-only options in a different way during config resolution. This may be good to explore in a PR maybe.

That being said, this is possible with the current design, it is just another concept users needs to be aware of. If we end up going with something like $client, I would argue that using top level for defaults consistently is better.

[patak-dev]

It is maybe a matter of perspective.

1. works exactly the same in the current API and in this proposal. SPA/MPA is fine with top level configs no matter if they are all defaults or some are client only.
2. (+3.) When you expand to SSR, I argue that you are already in a completely different land, where most of the configuration is done by framework authors instead of final users so we having a more consistent API instead of an easier story for the specific SSR environment may be a better tradeoff. So we only have 1. and (2.+3.), and not three steps.

Checking all options. Here is what is shared. This will be the same, no matter what design we choose.

root, base, mode, plugins, publicDir, cacheDir,
resolve.alias, resolve.preserveSymlinks, 
html, css, json, esbuild, assetsInclude, 
logLevel, customLogger, clearScreen, 
envDir, envPrefix, appType, future, worker, server (*)

(*) except for the server options that were moved to dev

These are the per-environment options:

dev, build, define, 
resolve.dedupe, resolve.external, resolve.noExternal, 
resolve.conditions, resolve.externalConditions, 
resolve.mainFields, resolve.extensions

Not counting dev, all these options currently are defaults for all environments. build options were always per-environment and the top level acted as a default. Same for resolve options. Changing this would involve breaking changes. So it seems we only need to focus on the dev options:

dev.warmup, dev.preTransformRequests, 
dev.sourcemap, dev.sourcemapIgnoreList, 
dev.optimizeDeps

If these are the only options that define if the top level keys should act as a default or be client-only, I think we can go either way to be honest. I would say that sourcemap and sourcemapIgnoreList are better as default. optimizeDeps is ok as default if we introduce optimizeDeps.enabled (false for consumer: 'server'). preTransformRequests is something that most users won't tinker with (and it is currently true by default only for consumer: 'client', so if a user toggles it for the client, it is the same for other envs). warmup` is interesting, maybe it is better for it to be client only, but if you check the current option, it is:

server: {
  warmup: {
    clientFiles: [

And the equivalent keeping it as a default, and using $client, would be

$client: {
  warmup: {
    files: [

The user already had to think about the client environment, so there isn't a big jump here.

I think there are also two different discussions here:
a. Should the top level keys be all defaults or a mix of client-only and defaults. Given the above, I think it is good to see if we can be consistent and have all options be defaults.
b. Should we treat the ssr environment in a special way compared to other server environments. My take with this is that the only special environment should be the client. The ssr environment is special only because of backward compatibility and at one point, once the mixed module graph and ssrLoadModule are no longer in use, we could remove any special considerations for the ssr named environment. Maybe we could discuss this in another thread, and keep this one for the defaults vs mixed top keys.

Note: There are some things that we should review. Rich asked for preview to be per-environment, so, do we need a previewer? Are there some options from build we should move to builder in the future? I don't want to mix this with the current thread, just saying it out loud as the above is a current best effort for this discussion, and probably not the full list of options we'll have in the future.

[bluwy]

Thanks for listing the options out and the very helpful overview. I am (finally (sorry 😄)) seeing your point now and the options listed help put things into perspective of what's actually needed per-environment.

It is maybe a matter of perspective.

1. It works the same, but there's a subtle implication that if you want to do it right, you should put the config in config.$client.* or config.environments.client.* (current) instead. There's now kinda two ways to do it, and people would for sure choose putting in config.$client.* because it scales better.
2. (no comment atm)

Replying to your discussion:

a. Like mentioned in no1 above, there's now kinda two ways to configure the client which isn't quite ideal. Hence I'm somewhat leaning towards top level keys being a mix of client-only and defaults still. Client config being front and center feels right to me because at the end you're configuring your app and not specifically thinking the client portion of it.
b. Probably discuss this in another thread yeah. I think it's something we can punt for later, but my gut feeling is to keep ssr still because Vite is opinionated and not for compat.

---

One thing I'm not sure is highlighted well in my proposal, is that environment types can control what environment-specific option is exposed. For example, perhaps workerd don't want anyone else to change config.$edge.resolve.conditions, the type can disallow configuring that, and top-level resolve.conditions isn't really a fallback anymore. The specific behaviour is each documented by the environment.

Not only that, it can control additional options to expose. Example 1: workerd might want users to configure config.$edge.polyfillNode: string[] | boolean and it can take part of config merging, I'm not sure the current API allows that. Example 2: we don't have a usecase for client to have build.emitAssets: false, supporting it may be confusing.

My suggestion is that environments internally can share the same base environment options for Vite to handle processing, but they can configure what to expose and apply different "resolved config" logic that doesn't necessarily need to mean "fallback to top-level options". I hope this trims down the API surface so users only configure options that matter, but I guess you could say the inconsistency at the end causes an even larger API surface. But I think there's value in this still.

[patak-dev]

Doesn't 1. goes both ways? In the mixed case, for some options users will need to use config.$ssr. for cases that before would be covered by the default top level key.

There are also a lot of options that would be by for all environments by default in your proposal too. So except for a handful of options, this would already be the case. A possible smaller change from your proposal we could apply is to keep things as is but not let users modify the client through the config to remove the noise that the "two ways of doing things" have for you. First, I would argue that this only being confusing for the client and not for the rest of the environments isn't right. We also lose consistency in letting users setup the client environment in the same way as the others (electronEnvironment() for example).

We will have two ways of doing things already for ssr and any other environment in any case. If the user have multiple environments already (so we are out of SPA/MPA land), then consistency wins for me.

(discussing the second part in another thread)

[bluwy]

If you're using SSR in the first place, you'd have a mix of client and server configurations, so it's easier to tell where you should put the configuration in. Putting in the top-level has the intent that you want the configuration to share among environments. Putting in config.$env means for that environment specifically.

If it's a plain SPA/MPA, then the top-level don't have the intent to share among environments, because there's only one which is the client. If we're saying that it's fine to put things on the top-level because you're developing an SPA/MPA (you get similar DX as before), and then also tuck some client-environment options in config.$client, it gets confusing where things should be placed IMO.

So there isn't two ways for the SSR + other environments case, only for SPA/MPA. But I agree there's consistency if you start dealing with more environments, but it goes back to my point:

as they usually try to optimize for general usage and scalability, and the abstraction hurts the initial/beginner adoption at the end.

(initial/beginner adoption refers to SPA/MPA, where basic apps start off with, and involve more environments later where they see fit.)

[patak-dev]

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.

[patak-dev]

@bluwy says:

One thing I'm not sure is highlighted well in my proposal, is that environment types can control what environment-specific option is exposed. For example, perhaps workerd don't want anyone else to change config.$edge.resolve.conditions, the type can disallow configuring that, and top-level resolve.conditions isn't really a fallback anymore. The specific behaviour is each documented by the environment.

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:

function opinionatedEdgeEnvironment(config: PartialUserConfig) {
  return {
    ...config,
    // some options that can't be overriden
  }
}

export default defineConfig({
  $edge: opinionatedEdgeEnvironment({
    // only some options are available, typing works fine
  })
}

Not only that, it can control additional options to expose. Example 1: workerd might want users to configure config.$edge.polyfillNode: string[] | boolean and it can take part of config merging, I'm not sure the current API allows that. Example 2: we don't have a usecase for client to have build.emitAssets: false, supporting it may be confusing.

This also works fine right now

function opinionatedEdgeEnvironment(config: ExtendedUserConfig) {
  const { a, b, c, ...userConfig } = config
  return {
    ...userConfig,
  }
}

My suggestion is that environments internally can share the same base environment options for Vite to handle processing, but they can configure what to expose and apply different "resolved config" logic that doesn't necessarily need to mean "fallback to top-level options". I hope this trims down the API surface so users only configure options that matter, but I guess you could say the inconsistency at the end causes an even larger API surface. But I think there's value in this still.

Environments are already using the pattern above if I understand correctly, so they see the value at least in extending with their own options.

[bluwy]

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.

[patak-dev]

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.