feat: extended applyToEnvironment and perEnvironmentPlugin (#18544)

Co-authored-by: 翠 / green <[email protected]>
Co-authored-by: Bjorn Lu <[email protected]>

Author: 3 people

changes/shared-plugins-during-build.md

@@ -59,11 +59,11 @@ function PerEnvironmentCountTransformedModulesPlugin() {
 }
 ```
 
-To simplify this pattern, internally in Vite, we use a `usePerEnvironmentState` helper:
+To simplify this pattern, Vite exports a `perEnvironmentState` helper:
 
 ```js
 function PerEnvironmentCountTransformedModulesPlugin() {
-  const state = usePerEnvironmentState<{ count: number }>(() => ({ count: 0 }))
+  const state = perEnvironmentState<{ count: number }>(() => ({ count: 0 }))
   return {
     name: 'count-transformed-modules',
     perEnvironmentStartEndDuringDev: true,

guide/api-environment-plugins.md

@@ -142,7 +142,8 @@ const UnoCssPlugin = () => {
       // use global hooks normally
     },
     applyToEnvironment(environment) {
-      // return true if this plugin should be active in this environment
+      // return true if this plugin should be active in this environment,
+      // or return a new plugin to replace it.
       // if the hook is not used, the plugin is active in all environments
     },
     resolveId(id, importer) {
@@ -152,6 +153,37 @@ const UnoCssPlugin = () => {
 }
 ```
 
+If a plugin isn't environment aware and has state that isn't keyed on the current environment, the `applyToEnvironment` hook allows to easily make it per-environment.
+
+```js
+import { nonShareablePlugin } from 'non-shareable-plugin'
+
+export default defineConfig({
+  plugins: [
+    {
+      name: 'per-environment-plugin',
+      applyToEnvironment(environment) {
+        return nonShareablePlugin({ outputName: environment.name })
+      },
+    },
+  ],
+})
+```
+
+Vite exports a `perEnvironmentPlugin` helper to simplify these cases where no other hooks are required:
+
+```js
+import { nonShareablePlugin } from 'non-shareable-plugin'
+
+export default defineConfig({
+  plugins: [
+    perEnvironmentPlugin('per-environment-plugin', (environment) =>
+      nonShareablePlugin({ outputName: environment.name }),
+    ),
+  ],
+})
+```
+
 ## Environment in build hooks
 
 In the same way as during dev, plugin hooks also receive the environment instance during build, replacing the `ssr` boolean.