feat: add callerName option to createRsbuild

e2e/cases/javascript-api/caller-name/index.test.ts

@@ -0,0 +1,27 @@
+import { expect } from '@playwright/test';
+import { createRsbuild } from '@rsbuild/core';
+import { rspackOnlyTest } from 'scripts';
+
+rspackOnlyTest(
+  'should allow to set caller name and use it in plugins',
+  async () => {
+    let callerName = '';
+    const rsbuild = await createRsbuild({
+      cwd: __dirname,
+      callerName: 'foo',
+      rsbuildConfig: {
+        plugins: [
+          {
+            name: 'foo',
+            setup(api) {
+              callerName = api.context.callerName;
+            },
+          },
+        ],
+      },
+    });
+
+    await rsbuild.build();
+    expect(callerName).toBe('foo');
+  },
+);

e2e/cases/javascript-api/caller-name/src/index.js

@@ -0,0 +1 @@
+console.log('hello');

packages/core/src/createContext.ts

@@ -160,6 +160,7 @@ export function createPublicContext(
     'distPath',
     'devServer',
     'cachePath',
+    'callerName',
     'bundlerType',
   ];
 
@@ -207,6 +208,7 @@ export async function createContext(
     rootPath,
     distPath: '',
     cachePath,
+    callerName: options.callerName,
     bundlerType,
     environments: {},
     hooks: initHooks(),

packages/core/src/createRsbuild.ts

@@ -171,6 +171,7 @@ export async function createRsbuild(
 
   const resolvedOptions: ResolvedCreateRsbuildOptions = {
     cwd: process.cwd(),
+    callerName: 'rsbuild',
     ...options,
     rsbuildConfig: config,
   };

packages/core/src/types/context.ts

@@ -32,6 +32,14 @@ export type RsbuildContext = {
    * The bundler type, can be `rspack` or `webpack`.
    */
   bundlerType: BundlerType;
+  /**
+   * The name of the framework or tool that is currently invoking Rsbuild,
+   * same as the `callerName` option in the `createRsbuild` method.
+   * @example
+   * - `rslib` is set when Rslib calls Rsbuild.
+   * - `rspress` is set when Rspress calls Rsbuild.
+   */
+  callerName: string;
 };
 
 /** The inner context. */

packages/core/src/types/rsbuild.ts

@@ -117,6 +117,13 @@ export type CreateRsbuildOptions = {
    * @default process.cwd()
    */
   cwd?: string;
+  /**
+   * The name of the framework or tool that is currently invoking Rsbuild.
+   * This allows plugins to tailor their behavior based on the calling context.
+   * Rsbuild plugins can access this value via `api.context.callerName`.
+   * @default 'rsbuild'
+   */
+  callerName?: string;
   /**
    * Only build specified environments.
    * For example, passing `['web']` will only build the `web` environment.
@@ -137,7 +144,7 @@ export type CreateRsbuildOptions = {
 };
 
 export type ResolvedCreateRsbuildOptions = Required<
-  Pick<CreateRsbuildOptions, 'cwd'>
+  Pick<CreateRsbuildOptions, 'cwd' | 'callerName'>
 > &
   Pick<CreateRsbuildOptions, 'loadEnv' | 'environment'> & {
     rsbuildConfig: RsbuildConfig;

website/docs/en/api/javascript-api/core.mdx

@@ -33,16 +33,18 @@ The first parameter of `createRsbuild` is an `options` object, you can pass in t
 ```ts
 type CreateRsbuildOptions = {
   cwd?: string;
+  callerName?: string;
   environment?: string[];
-  rsbuildConfig?: RsbuildConfig | (() => Promise<RsbuildConfig>);
   loadEnv?: boolean | LoadEnvOptions;
+  rsbuildConfig?: RsbuildConfig | (() => Promise<RsbuildConfig>);
 };
 ```
 
 - `cwd`: The root path of the current build, defaults to `process.cwd()`.
+- `callerName`: The name of the framework or tool that is currently invoking Rsbuild, defaults to `rsbuild`, see [Specify caller name](#specify-caller-name).
 - `environment`: Only build specified [environments](/guide/advanced/environments). If not specified or passing an empty array, all environments will be built.
-- `rsbuildConfig`: Rsbuild configuration object. Refer to [Configuration Overview](/config/) for all available configuration options.
 - `loadEnv`：Whether to call the [loadEnv](/api/javascript-api/core#loadenv) method to load env variables and define them as global variables via [source.define](/config/source/define).
+- `rsbuildConfig`: Rsbuild configuration object. Refer to [Configuration Overview](/config/) for all available configuration options.
 
 ### Load configuration async
 
@@ -87,6 +89,36 @@ const rsbuild = await createRsbuild({
 });
 ```
 
+### Specify caller name
+
+You can specify the name of the framework or tool that is currently invoking Rsbuild, which can be accessed by Rsbuild plugins through [context.callerName](/api/javascript-api/instance#contextcallername), and execute different logic based on this identifier.
+
+```ts
+import { myPlugin } from './myPlugin';
+
+const rsbuild = await createRsbuild({
+  callerName: 'rslib',
+  rsbuildConfig: {
+    plugins: [myPlugin],
+  },
+});
+```
+
+```ts title="myPlugin.ts"
+export const myPlugin = {
+  name: 'my-plugin',
+  setup(api) {
+    const { callerName } = api.context;
+
+    if (callerName === 'rslib') {
+      // ...
+    } else if (callerName === 'rsbuild') {
+      // ...
+    }
+  },
+};
+```
+
 ## loadConfig
 
 Load Rsbuild configuration file.

website/docs/en/api/javascript-api/instance.mdx

@@ -50,6 +50,29 @@ The absolute path of the build cache files.
 type CachePath = string;
 ```
 
+### context.callerName
+
+The name of the framework or tool that is currently invoking Rsbuild, same as the [callerName](/api/javascript-api/core#specify-caller-name) option in the [createRsbuild](/api/javascript-api/core#creatersbuild) method.
+
+- **Type:** `string`
+- **Default:** `rsbuild`
+- **Example:**
+
+```ts title="myPlugin.ts"
+export const myPlugin = {
+  name: 'my-plugin',
+  setup(api) {
+    const { callerName } = api.context;
+
+    if (callerName === 'rslib') {
+      // ...
+    } else if (callerName === 'rsbuild') {
+      // ...
+    }
+  },
+};
+```
+
 ### context.devServer
 
 Dev server information, including the current dev server hostname and port number.

website/docs/zh/api/javascript-api/core.mdx

@@ -33,16 +33,18 @@ const rsbuild = await createRsbuild({
 ```ts
 type CreateRsbuildOptions = {
   cwd?: string;
+  callerName?: string;
   environment?: string[];
-  rsbuildConfig?: RsbuildConfig | (() => Promise<RsbuildConfig>);
   loadEnv?: boolean | LoadEnvOptions;
+  rsbuildConfig?: RsbuildConfig | (() => Promise<RsbuildConfig>);
 };
 ```
 
 - `cwd`：当前执行构建的根路径，默认值为 `process.cwd()`
+- `callerName`：当前调用者的名称，默认值为 `rsbuild`，详见 [指定调用者名称](#指定调用者名称)。
 - `environment`：只构建指定的 [environments](/guide/advanced/environments)，如果未指定或传入空数组，则构建所有环境。
-- `rsbuildConfig`：Rsbuild 配置对象。参考 [配置总览](/config/) 查看所有可用的配置项。
 - `loadEnv`：是否调用 [loadEnv](/api/javascript-api/core#loadenv) 方法来加载环境变量，并通过 [source.define](/config/source/define) 定义为全局变量。
+- `rsbuildConfig`：Rsbuild 配置对象。参考 [配置总览](/config/) 查看所有可用的配置项。
 
 ### 异步加载配置
 
@@ -87,6 +89,36 @@ const rsbuild = await createRsbuild({
 });
 ```
 
+### 指定调用者名称
+
+你可以通过 `callerName` 选项来指定当前调用 Rsbuild 的框架或工具的名称，该名称可以被 Rsbuild 插件通过 [context.callerName](/api/javascript-api/instance#contextcallername) 访问到，并基于这个标识符来执行不同的逻辑。
+
+```ts
+import { myPlugin } from './myPlugin';
+
+const rsbuild = await createRsbuild({
+  callerName: 'rslib',
+  rsbuildConfig: {
+    plugins: [myPlugin],
+  },
+});
+```
+
+```ts title="myPlugin.ts"
+export const myPlugin = {
+  name: 'my-plugin',
+  setup(api) {
+    const { callerName } = api.context;
+
+    if (callerName === 'rslib') {
+      // ...
+    } else if (callerName === 'rsbuild') {
+      // ...
+    }
+  },
+};
+```
+
 ## loadConfig
 
 加载 Rsbuild 配置文件。

website/docs/zh/api/javascript-api/instance.mdx

@@ -50,6 +50,29 @@ type DistPath = string;
 type CachePath = string;
 ```
 
+### context.callerName
+
+当前调用 Rsbuild 的框架或工具的名称，与 [createRsbuild](/api/javascript-api/core#creatersbuild) 方法中的 [callerName](/api/javascript-api/core#指定调用者名称) 选项相同。
+
+- **类型：** `string`
+- **默认值：** `rsbuild`
+- **示例：**
+
+```ts title="myPlugin.ts"
+export const myPlugin = {
+  name: 'my-plugin',
+  setup(api) {
+    const { callerName } = api.context;
+
+    if (callerName === 'rslib') {
+      // ...
+    } else if (callerName === 'rsbuild') {
+      // ...
+    }
+  },
+};
+```
+
 ### context.devServer
 
 Dev server 相关信息，包含了当前 dev server 的 hostname 和端口号。