docs: per-environment state in plugins (#2033)

Author: jay-es

guide/api-environment-plugins.md

@@ -126,6 +126,29 @@ interface HotUpdateOptions {
   }
   ```
 
+## プラグインにおける環境ごとの状態 {#per-environment-state-in-plugins}
+
+同じプラグインインスタンスが異なる環境で使用されるため、プラグインの状態は `this.environment` をキーとして管理する必要があります。これは、エコシステムがクライアントモジュールと SSR モジュールの状態が混ざるのを避けるために、`ssr` ブール値をキーとしてモジュールの状態を保持するために既に使用しているパターンと同じです。`Map<Environment, State>` を使用して、各環境の状態を個別に保持できます。後方互換性のため、`buildStart` および `buildEnd` は、`perEnvironmentStartEndDuringDev: true` フラグがない場合、クライアント環境に対してのみ呼び出されることに注意してください。
+
+```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)
+    }
+  }
+}
+```
+
 ## 環境ごとのプラグイン {#per-environment-plugins}
 
 プラグインは `applyToEnvironment` 関数で、適用する環境を定義できます。