feat: v6 - Environment API

[patak-dev]

Description

Note

Check out the Environment API Docs

We're starting a new PR for the Environment API work in progress proposal for v6 to have a clean slate for reviews and discussions now that the implementation and docs are more stable.

This PR merges the work done in:

• feat: environment api #16129
• docs: environment API proposal #16089

Refer to the discussions in these PRs for context. If you have general feedback about the APIs, let's use this discussion so we can have proper threads:

• Environment API #16358

If you have comments about the implementation or would like to collaborate a feature, fix, test, or docs, please comment in this PR as an usual review or send a PR against the v6/environment-api branch.

[stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[hi-ogawa]

After 2866d4f, we have opt-in for build plugins to be shared, matching the way things work during dev. Individual plugins can set a sharedDuringBuild: true to opt-in, ...

I experimented with sharedDuringBuild for unocss on multi environment use cases (namely react server component) hi-ogawa/vite-environment-examples#57. It's still a minimal proof-of-concept (I picked up some code from original unocss plugin and tailwind v4 plugin), but my impression is that create(environment) and sharedDuringBuild: true nicely solved the concerns I had with using unocss for RSC. Awesome work!

It feels really nice to use, so only positive feedback here to confirm if I'm using it right:

• since create(environment) provides environment.mode: "dev" | "build", I use it to split plugins for dev/build as well.
• since environment already has environment.config, hot, moduleGraph etc..., I didn't need to access specific environment via server.environments.(env) via configureServer(server)

[patak-dev]

It feels really nice to use, so only positive feedback here to confirm if I'm using it right:

• since create(environment) provides environment.mode: "dev" | "build", I use it to split plugins for dev/build as well.

Yes, I think it makes sense to do it there. apply let's you do the same for a shared plugin so I think it still makes sense to also keep it.

• since environment already has environment.config, hot, moduleGraph etc..., I didn't need to access specific environment via server.environments.(env) via configureServer(server)

You shouldn't be doing it either for shared plugins. You'll directly use this.environment in the hooks. We removed all configureServer(server) to access these in Vite's core. Or maybe you have other needs? Could you expand into why this.environment wasn't enough?

[hi-ogawa]

• since environment already has environment.config, hot, moduleGraph etc..., I didn't need to access specific environment via server.environments.(env) via configureServer(server)

You shouldn't be doing it either for shared plugins. You'll directly use this.environment in the hooks. We removed all configureServer(server) to access these in Vite's core. Or maybe you have other needs? Could you expand into why this.environment wasn't enough?

Indeed, calling this.environment.hot during transform where the tokens are extracted can work normally, but it was a reminiscent of the original unocss plugin as it provides asynchronous onInvalidate listener, so I was setting up environment.hot callback there, something like:

export function vitePluginSharedUnocss(): Plugin {
  const ctx = getUnocssContext();

  return {
    ...
    create(environment) {
      if (environment.mode === "dev") {
        ctx.onInvalidate(() => environment.hot.send( .... ));
      }
      ...
    }
  }
}

[patak-dev]

Indeed, calling this.environment.hot during transform where the tokens are extracted can work normally, but it was a reminiscent of the original unocss plugin as it provides asynchronous onInvalidate listener, so I was setting up environment.hot callback there (...)

Ah, this makes sense. Then yes, the new create hook is a good place to setup this listener. We should check if the listener is really needed now though. Interesting use case, thanks!

[patak-dev]

We discussed with @sapphi-red and he proposed we move away from the create hook for bounded plugins, and use a factory (both Anthony and me preferred this form too initially). I actually started using a factory but switched to the create hook for the following reasons that I now think are not real blockers:

• I felt that a function may not be enough in the future, imagine if we want to add more things like enforce or apply that needs to happen before the plugin gets evaluated. I think this may be a no-problem though, as we can first evaluate and then check the flags.
• I thought that it wasn't easy to support enforce and that it would be needed. For example:

  function frameworkPlugin() {
    return [
      sharedPlugin(), // can have enforce: 'pre'
      () => isolatedPlugin() // it will stay separated from the prev plugin
    ]
  }

  This wasn't that bad at the end, enforce works in bounded plugins now
• apply is evaluated before environments are created, so we need to make the last environment param optional or have a new hook. I think it isn't needed though, because we can pass environment as the argument when constructing the isolated plugin and that can be used for filtering
• I thought that it will be easier to have backward compat with the create hook. Imagine if someone is reading plugins and now PluginOption also can be a function. We could have code broken at runtime or at types level. Maybe it is a price we should pay though.
• I was also afraid that frameworks could not sniff the plugins to remove these isolated factories at config time anymore. But now that I think about it, we can use the same trick we have for middlewares and properly name the constructor functions so they could still remove them if they want. Or we only use shared plugins internally.

After [email protected], instead of

function plugin() {
  return {
    name: 'shared-plugin',
    create(environment) {
      return {
        name: 'bounded-plugin',
        transform() { ... }
      }
    }
  }
}

we switched to

function plugin() {
  return (environment) => {
    return {
      name: 'bounded-plugin',
      transform() { ... }
    }
  }
}

@hi-ogawa for the case you were having both a shared plugin hook and create in the same plugin, you can get the same by returning an array:

  [
    { name: 'shared-plugin', ... },
    (environment) => ({ name: 'bounded-plugin', ... }),
  ]

[patak-dev]

/ecosystem-ci run

[hi-ogawa]

It looks like currently optimizeDeps.entries is not exposed (entries is in DepOptimizationOptions instead of DepOptimizationConfig). Is this intended?

  environments: {
    client: {
      dev: {
        optimizeDeps: {
          // this is currently type error
          entries: []
        },
      },

[patak-dev]

Could you expand on a good use case for having different entries? These are only used while scanning, that is currently only enabled for the client environment. This is now an artificial limitation though. Given that we can properly issue a reload for all environments, we could opt-in into the full scanning + registering missing dependencies instead of a static list if we want.

[hi-ogawa]

Right, what I meant is only for client environment, just something equivalent of current root optimizeDeps.entries to help discovering deps early using initial esbuild scan.

[patak-dev]

The current config.optimizeDeps.entries will be used during scan. But I think we should move it to environment options 👍🏼

[vite-ecosystem-ci]

📝 Ran ecosystem CI on cf9a79c: Open

suite	result	latest scheduled
analogjs	❌ failure	✅ success
astro	❌ failure	✅ success
histoire	❌ failure	✅ success
marko	❌ failure	✅ success
nuxt	❌ failure	✅ success
previewjs	❌ failure	✅ success
quasar	❌ failure	✅ success
qwik	❌ failure	✅ success
remix	❌ failure	✅ success
sveltekit	❌ failure	✅ success
unocss	❌ failure	✅ success
vike	❌ failure	✅ success
vite-plugin-react-swc	❌ failure	✅ success
vite-plugin-svelte	❌ failure	✅ success
vite-plugin-vue	❌ failure	✅ success
vite-setup-catalogue	❌ failure	✅ success
vitepress	❌ failure	✅ success
vitest	❌ failure	❌ failure

✅ ladle, laravel, rakkas, vite-plugin-pwa, vite-plugin-react, vite-plugin-react-pages