From b1fa531bb39360fe058053ddc4b14434b6d18f3d Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Tue, 21 Oct 2025 19:12:08 +0800
Subject: [PATCH 1/2] docs: add section about extending plugin API

---
 website/docs/en/plugins/dev/index.mdx | 50 +++++++++++++++++++++++++++
 website/docs/zh/plugins/dev/index.mdx | 48 +++++++++++++++++++++++++
 2 files changed, 98 insertions(+)

diff --git a/website/docs/en/plugins/dev/index.mdx b/website/docs/en/plugins/dev/index.mdx
index e4af78e014..4e98cdf1c1 100644
--- a/website/docs/en/plugins/dev/index.mdx
+++ b/website/docs/en/plugins/dev/index.mdx
@@ -297,3 +297,53 @@ export const pluginEslint = (options?: Options): RsbuildPlugin => ({
   },
 });
 ```
+
+## Extending the Plugin API
+
+When building custom tools on top of Rsbuild's [JavaScript API](/api/start/), you may want to extend the existing plugin API to provide additional capabilities — for example, exposing utility functions or sharing context objects.
+
+You can achieve this by using the [rsbuild.expose()](/api/javascript-api/instance#rsbuildexpose) method on the Rsbuild instance.
+
+This method works the same way as the plugin's [api.expose()](/plugins/dev/core#apiexpose), allowing you to expose custom methods or objects to Rsbuild plugins.
+
+For example, you can expose `getState` and `setCount` methods:
+
+```ts title="myToolkit.ts"
+import { createRsbuild } from '@rsbuild/core';
+
+export const MY_TOOLKIT_ID = 'my-toolkit';
+
+const rsbuild = await createRsbuild({
+  // ...
+});
+
+const state = {
+  count: 0,
+};
+
+rsbuild.expose(MY_TOOLKIT_ID, {
+  getState() {
+    return state;
+  },
+  setCount(count: number) {
+    state.count = count;
+  },
+});
+```
+
+Plugins can then access these extended APIs using the [api.useExposed()](/plugins/dev/core#apiuseexposed) method:
+
+```ts title="myPlugin.ts"
+import { MY_TOOLKIT_ID } from './myToolkit';
+
+const myPlugin = {
+  name: 'my-plugin',
+  setup(api) {
+    const toolkitApi = api.useExposed(MY_TOOLKIT_ID);
+    if (toolkitApi) {
+      const { count } = toolkitApi.getState();
+      toolkitApi.setCount(count + 1);
+    }
+  },
+};
+```
diff --git a/website/docs/zh/plugins/dev/index.mdx b/website/docs/zh/plugins/dev/index.mdx
index b8332e8db1..1f02f3ae92 100644
--- a/website/docs/zh/plugins/dev/index.mdx
+++ b/website/docs/zh/plugins/dev/index.mdx
@@ -296,3 +296,51 @@ export const pluginEslint = (options?: Options): RsbuildPlugin => ({
   },
 });
 ```
+
+## 扩展插件 API
+
+当你基于 Rsbuild 的 [JavaScript API](/api/start/) 来实现自定义的工具时，可能希望在现有插件 API 的基础上，提供更多能力，例如添加工具方法或共享上下文对象。
+
+此时，你可以使用 Rsbuild 实例上的 [rsbuild.expose()](/api/javascript-api/instance#rsbuildexpose) 方法。它的作用与插件的 [api.expose()](/plugins/dev/core#apiexpose) 一致，用于向 Rsbuild 插件暴露自定义的方法或对象。
+
+例如，向插件暴露 `getState` 和 `setCount` 方法：
+
+```ts title="myToolkit.ts"
+import { createRsbuild } from '@rsbuild/core';
+
+export const MY_TOOLKIT_ID = 'my-toolkit';
+
+const rsbuild = await createRsbuild({
+  // ...
+});
+
+const state = {
+  count: 0,
+};
+
+rsbuild.expose(MY_TOOLKIT_ID, {
+  getState() {
+    return state;
+  },
+  setCount(count: number) {
+    state.count = count;
+  },
+});
+```
+
+然后，插件可以通过 [api.useExposed()](/plugins/dev/core#apiuseexposed) 方法访问这些扩展 API：
+
+```ts title="myPlugin.ts"
+import { MY_TOOLKIT_ID } from './myToolkit';
+
+const myPlugin = {
+  name: 'my-plugin',
+  setup(api) {
+    const toolkitApi = api.useExposed(MY_TOOLKIT_ID);
+    if (toolkitApi) {
+      const { count } = toolkitApi.getState();
+      toolkitApi.setCount(count + 1);
+    }
+  },
+};
+```

From b15c74b7386e716e61d4eae571e909236e7e9339 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Tue, 21 Oct 2025 19:17:35 +0800
Subject: [PATCH 2/2] fix

---
 website/docs/en/plugins/dev/index.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/docs/en/plugins/dev/index.mdx b/website/docs/en/plugins/dev/index.mdx
index 4e98cdf1c1..30fd314995 100644
--- a/website/docs/en/plugins/dev/index.mdx
+++ b/website/docs/en/plugins/dev/index.mdx
@@ -298,7 +298,7 @@ export const pluginEslint = (options?: Options): RsbuildPlugin => ({
 });
 ```
 
-## Extending the Plugin API
+## Extending plugin API
 
 When building custom tools on top of Rsbuild's [JavaScript API](/api/start/), you may want to extend the existing plugin API to provide additional capabilities — for example, exposing utility functions or sharing context objects.