docs: missing changes guides (#18491)

Author: patak-dev

docs/changes/per-environment-apis.md

@@ -4,16 +4,12 @@
 Give us feedback at [Environment API feedback discussion](https://github.com/vitejs/vite/discussions/16358)
 :::
 
-Multiple APIs from ViteDevServer related to module graph has replaced with more isolated Environment APIs.
-
-- `server.moduleGraph` -> [`environment.moduleGraph`](/guide/api-environment#separate-module-graphs)
-- `server.transformRequest` -> `environment.transformRequest`
-- `server.warmupRequest` -> `environment.warmupRequest`
+Multiple APIs from `ViteDevServer` related to module graph and modules transforms have been moved to the `DevEnvironment` instances.
 
 Affect scope: `Vite Plugin Authors`
 
 ::: warning Future Deprecation
-The Environment instance was first introduced at `v6.0`. The deprecation of `server.moduleGraph` and other methods that are now in environments is planned for `v7.0`. We don't recommend moving away from server methods yet. To identify your usage, set these in your vite config.
+The `Environment` instance was first introduced at `v6.0`. The deprecation of `server.moduleGraph` and other methods that are now in environments is planned for `v7.0`. We don't recommend moving away from server methods yet. To identify your usage, set these in your vite config.
 
 ```ts
 future: {
@@ -26,8 +22,12 @@ future: {
 
 ## Motivation
 
-// TODO:
+In Vite v5 and before, a single Vite dev server always had two environments (`client` and `ssr`). The `server.moduleGraph` had mixed modules from both of these environments. Nodes were connected through `clientImportedModules` and `ssrImportedModules` lists (but a single `importers` list was maintained for each). A transformed module was represented by an `id` and a `ssr` boolean. This boolean needed to be passed to APIs, for example `server.moduleGraph.getModuleByUrl(url, ssr)` and `server.transformRequest(url, { ssr })`.
+
+In Vite v6, it is now possible to create any number of custom environments (`client`, `ssr`, `edge`, etc). A single `ssr` boolean isn't enough anymore. Instead of changing the APIs to be of the form `server.transformRequest(url, { environment })`, we moved these methods to the environment instance allowing them to be called without a Vite dev server.
 
 ## Migration Guide
 
-// TODO:
+- `server.moduleGraph` -> [`environment.moduleGraph`](/guide/api-environment#separate-module-graphs)
+- `server.transformRequest(url, ssr)` -> `environment.transformRequest(url)`
+- `server.warmupRequest(url, ssr)` -> `environment.warmupRequest(url)`

docs/changes/shared-plugins-during-build.md

@@ -4,7 +4,6 @@
 Give us feedback at [Environment API feedback discussion](https://github.com/vitejs/vite/discussions/16358)
 :::
 
-// TODO:
 See [Shared plugins during build](/guide/api-environment.md#shared-plugins-during-build).
 
 Affect scope: `Vite Plugin Authors`
@@ -15,8 +14,68 @@ Affect scope: `Vite Plugin Authors`
 
 ## Motivation
 
-// TODO:
+Align dev and build plugin pipelines.
 
 ## Migration Guide
 
-// TODO:
+To be able to share plugins across environments, plugin state must be keyed by the current environment. A plugin of the following form will count the number of transformed modules across all environments.
+
+```js
+function CountTransformedModulesPlugin() {
+  let transformedModules
+  return {
+    name: 'count-transformed-modules',
+    buildStart() {
+      transformedModules = 0
+    },
+    transform(id) {
+      transformedModules++
+    },
+    buildEnd() {
+      console.log(transformedModules)
+    },
+  }
+}
+```
+
+If we instead want to count the number of transformed modules for each environment, we need to keep a map:
+
+```js
+function PerEnvironmentCountTransformedModulesPlugin() {
+  const state = new Map<Environment, { count: number }>()
+  return {
+    name: 'count-transformed-modules',
+    perEnvironmentStartEndDuringDev: true,
+    buildStart() {
+      state.set(this.environment, { count: 0 })
+    }
+    transform(id) {
+      state.get(this.environment).count++
+    },
+    buildEnd() {
+      console.log(this.environment.name, state.get(this.environment).count)
+    }
+  }
+}
+```
+
+To simplify this pattern, internally in Vite, we use a `usePerEnvironmentState` helper:
+
+```js
+function PerEnvironmentCountTransformedModulesPlugin() {
+  const state = usePerEnvironmentState<{ count: number }>(() => ({ count: 0 }))
+  return {
+    name: 'count-transformed-modules',
+    perEnvironmentStartEndDuringDev: true,
+    buildStart() {
+      state(this).count = 0
+    }
+    transform(id) {
+      state(this).count++
+    },
+    buildEnd() {
+      console.log(this.environment.name, state(this).count)
+    }
+  }
+}
+```

packages/vite/src/node/server/index.ts

@@ -169,7 +169,7 @@ export interface ServerOptions extends CommonServerOptions {
    * @default false
    * @experimental
    */
-  perEnvironmentBuildStartEnd?: boolean
+  perEnvironmentStartEndDuringDev?: boolean
   /**
    * Run HMR tasks, by default the HMR propagation is done in parallel for all environments
    * @experimental
@@ -1033,7 +1033,7 @@ export function resolveServerOptions(
 ): ResolvedServerOptions {
   const server: ResolvedServerOptions = {
     preTransformRequests: true,
-    perEnvironmentBuildStartEnd: false,
+    perEnvironmentStartEndDuringDev: false,
     ...(raw as Omit<ResolvedServerOptions, 'sourcemapIgnoreList'>),
     sourcemapIgnoreList:
       raw?.sourcemapIgnoreList === false