From 7cb1b0828d58fcddd0c9c82b9aace3878c0207b9 Mon Sep 17 00:00:00 2001
From: Jun Shindo <46585162+jay-es@users.noreply.github.com>
Date: Tue, 24 Jun 2025 19:16:16 +0900
Subject: [PATCH] docs: per-environment state in plugins

---
 guide/api-environment-plugins.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/guide/api-environment-plugins.md b/guide/api-environment-plugins.md
index 0832ae6a..5324120a 100644
--- a/guide/api-environment-plugins.md
+++ b/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` 関数で、適用する環境を定義できます。