feat!: output inspect config to .rsbuild dir (#3189)

e2e/cases/cli/inspect/index.test.ts

@@ -16,7 +16,7 @@ test('should run inspect command correctly', async () => {
     cwd: __dirname,
   });
 
-  const files = await globContentJSON(path.join(__dirname, 'dist'));
+  const files = await globContentJSON(path.join(__dirname, 'dist/.rsbuild'));
   const fileNames = Object.keys(files);
 
   const rsbuildConfig = fileNames.find((item) =>
@@ -40,7 +40,7 @@ test('should run inspect command with mode option correctly', async () => {
     cwd: __dirname,
   });
 
-  const files = await globContentJSON(path.join(__dirname, 'dist'));
+  const files = await globContentJSON(path.join(__dirname, 'dist/.rsbuild'));
   const fileNames = Object.keys(files);
 
   const rsbuildConfig = fileNames.find((item) =>

e2e/cases/inspect-config/debug.test.ts

@@ -5,12 +5,12 @@ import { expect, test } from '@playwright/test';
 import { logger } from '@rsbuild/core';
 
 const getRsbuildConfig = (dist: string) =>
-  path.resolve(__dirname, `./${dist}/rsbuild.config.mjs`);
+  path.resolve(__dirname, `./${dist}/.rsbuild/rsbuild.config.mjs`);
 
 const getBundlerConfig = (dist: string) =>
   path.resolve(
     __dirname,
-    `./${dist}/${process.env.PROVIDE_TYPE || 'rspack'}.config.web.mjs`,
+    `./${dist}/.rsbuild/${process.env.PROVIDE_TYPE || 'rspack'}.config.web.mjs`,
   );
 
 test('should generate config files when build (with DEBUG)', async () => {

e2e/cases/inspect-config/index.test.ts

@@ -3,19 +3,22 @@ import path from 'node:path';
 import { createRsbuild } from '@e2e/helper';
 import { expect, test } from '@playwright/test';
 
-const rsbuildConfig = path.resolve(__dirname, './dist/rsbuild.config.mjs');
+const rsbuildConfig = path.resolve(
+  __dirname,
+  './dist/.rsbuild/rsbuild.config.mjs',
+);
 
 const rsbuildNodeConfig = path.resolve(
   __dirname,
-  './dist/rsbuild.config.node.mjs',
+  './dist/.rsbuild/rsbuild.config.node.mjs',
 );
 const bundlerConfig = path.resolve(
   __dirname,
-  `./dist/${process.env.PROVIDE_TYPE || 'rspack'}.config.web.mjs`,
+  `./dist/.rsbuild/${process.env.PROVIDE_TYPE || 'rspack'}.config.web.mjs`,
 );
 const bundlerNodeConfig = path.resolve(
   __dirname,
-  `./dist/${process.env.PROVIDE_TYPE || 'rspack'}.config.node.mjs`,
+  `./dist/.rsbuild/${process.env.PROVIDE_TYPE || 'rspack'}.config.node.mjs`,
 );
 
 test('should generate config files when writeToDisk is true', async () => {

packages/compat/webpack/src/inspectConfig.ts

@@ -21,7 +21,7 @@ const getInspectOutputPath = (
     return join(context.distPath, inspectOptions.outputPath);
   }
 
-  return context.distPath;
+  return join(context.distPath, '.rsbuild');
 };
 
 export async function inspectConfig({

packages/core/src/constants.ts

@@ -16,6 +16,7 @@ export const STATIC_PATH: string = join(__dirname, '../static');
 export const COMPILED_PATH: string = join(__dirname, '../compiled');
 export const TS_CONFIG_FILE = 'tsconfig.json';
 export const HMR_SOCKET_PATH = '/rsbuild-hmr';
+export const RSBUILD_OUTPUTS_PATH = '.rsbuild';
 
 // Defaults
 export const DEFAULT_PORT = 3000;

packages/core/src/plugins/cleanOutput.ts

@@ -1,5 +1,6 @@
-import { sep } from 'node:path';
+import { join, sep } from 'node:path';
 import color from 'picocolors';
+import { RSBUILD_OUTPUTS_PATH } from '../constants';
 import { emptyDir } from '../helpers';
 import { logger } from '../logger';
 import type { EnvironmentContext, RsbuildPlugin } from '../types';
@@ -12,11 +13,38 @@ const isStrictSubdir = (parent: string, child: string) => {
   return parentDir !== childDir && childDir.startsWith(parentDir);
 };
 
+export const dedupeCleanPaths = (paths: string[]): string[] => {
+  return paths
+    .sort((p1, p2) => (p2.length > p1.length ? -1 : 1))
+    .reduce<string[]>((prev, curr) => {
+      const isSub = prev.find((p) => curr.startsWith(p) || curr === p);
+      if (isSub) {
+        return prev;
+      }
+
+      return prev.concat(curr);
+    }, []);
+};
+
 export const pluginCleanOutput = (): RsbuildPlugin => ({
   name: 'rsbuild:clean-output',
 
   setup(api) {
-    const clean = async (environment: EnvironmentContext) => {
+    // should clean rsbuild outputs, such as inspect files
+    const getRsbuildCleanPath = () => {
+      const { rootPath, distPath } = api.context;
+      const config = api.getNormalizedConfig();
+      const cleanPath = join(distPath, RSBUILD_OUTPUTS_PATH);
+
+      const { cleanDistPath } = config.output;
+
+      if (cleanDistPath && isStrictSubdir(rootPath, cleanPath)) {
+        return cleanPath;
+      }
+      return undefined;
+    };
+
+    const getCleanPath = (environment: EnvironmentContext) => {
       const { rootPath } = api.context;
       const { config, distPath } = environment;
 
@@ -39,8 +67,9 @@ export const pluginCleanOutput = (): RsbuildPlugin => ({
       }
 
       if (cleanDistPath) {
-        await emptyDir(distPath);
+        return distPath;
       }
+      return undefined;
     };
 
     const cleanAll = async (params: {
@@ -55,7 +84,12 @@ export const pluginCleanOutput = (): RsbuildPlugin => ({
         return total;
       }, []);
 
-      await Promise.all(environments.map((e) => clean(e)));
+      const cleanPaths = environments
+        .map((e) => getCleanPath(e))
+        .concat(getRsbuildCleanPath())
+        .filter((p): p is string => !!p);
+
+      await Promise.all(dedupeCleanPaths(cleanPaths).map((p) => emptyDir(p)));
     };
 
     api.onBeforeBuild(async ({ isFirstCompile, environments }) => {

packages/core/src/provider/inspectConfig.ts

@@ -4,6 +4,7 @@ import {
   outputInspectConfigFiles,
   stringifyConfig,
 } from '../config';
+import { RSBUILD_OUTPUTS_PATH } from '../constants';
 import { getNodeEnv, setNodeEnv } from '../helpers';
 import type {
   InspectConfigOptions,
@@ -25,7 +26,7 @@ const getInspectOutputPath = (
     return join(context.distPath, inspectOptions.outputPath);
   }
 
-  return context.distPath;
+  return join(context.distPath, RSBUILD_OUTPUTS_PATH);
 };
 
 export async function inspectConfig({

packages/core/tests/cleanOutput.test.ts

@@ -0,0 +1,34 @@
+import { dedupeCleanPaths } from '../src/plugins/cleanOutput';
+
+describe('cleanOutput', () => {
+  test('should dedupeCleanPaths correctly', async () => {
+    expect(
+      dedupeCleanPaths([
+        'package/to/root/dist/web1',
+        'package/to/root/dist/web2',
+        'package/to/root/dist',
+      ]),
+    ).toEqual(['package/to/root/dist']);
+
+    expect(
+      dedupeCleanPaths([
+        'package/to/root',
+        'package/to/root/dist/web2',
+        'package/to/root/dist',
+      ]),
+    ).toEqual(['package/to/root']);
+
+    expect(
+      dedupeCleanPaths([
+        'package/to/root/dist/web1',
+        'package/to/root/dist/web2',
+        'package/to/root/dist/web3',
+        'package/to/root/dist/web3',
+      ]),
+    ).toEqual([
+      'package/to/root/dist/web1',
+      'package/to/root/dist/web2',
+      'package/to/root/dist/web3',
+    ]);
+  });
+});

website/docs/en/guide/advanced/environments.mdx

@@ -74,10 +74,10 @@ When you execute the command `npx rsbuild inspect` in the project root directory
 
 Inspect config succeed, open following files to view the content:
 
-  - Rsbuild Config (web): /project/dist/rsbuild.config.web.mjs
-  - Rsbuild Config (node): /project/dist/rsbuild.config.node.mjs
-  - Rspack Config (web): /project/dist/rspack.config.web.mjs
-  - Rspack Config (node): /project/dist/rspack.config.node.mjs
+  - Rsbuild Config (web): /project/dist/.rsbuild/rsbuild.config.web.mjs
+  - Rsbuild Config (node): /project/dist/.rsbuild/rsbuild.config.node.mjs
+  - Rspack Config (web): /project/dist/.rsbuild/rspack.config.web.mjs
+  - Rspack Config (node): /project/dist/.rsbuild/rspack.config.node.mjs
 ```
 
 ## Default environment

website/docs/en/guide/basic/cli.mdx

@@ -128,7 +128,7 @@ Options:
   -h, --help            show command help
 ```
 
-When you run the command `npx rsbuild inspect` in the project root directory, the following files will be generated in the `dist` directory of the project:
+When you run the command `npx rsbuild inspect` in the project root directory, the following files will be generated in the `dist/.rsbuild` directory of the project:
 
 - `rsbuild.config.mjs`: Represents the Rsbuild configuration used during the build.
 - `rspack.config.web.mjs`: Represents the Rspack configuration used during the build.
@@ -138,8 +138,8 @@ When you run the command `npx rsbuild inspect` in the project root directory, th
 
 Inspect config succeed, open following files to view the content:
 
-  - Rsbuild Config: /project/dist/rsbuild.config.mjs
-  - Rspack Config (web): /project/dist/rspack.config.web.mjs
+  - Rsbuild Config: /project/dist/.rsbuild/rsbuild.config.mjs
+  - Rspack Config (web): /project/dist/.rsbuild/rspack.config.web.mjs
 ```
 
 ### Specifying Mode
@@ -160,14 +160,14 @@ rsbuild inspect --verbose
 
 ### Multiple Targets
 
-If the current project has multiple build targets, such as building browser artifact and Node.js artifact simultaneously, multiple Rspack configuration files will be generated in the `dist` directory.
+If the current project has multiple build targets, such as building browser artifact and Node.js artifact simultaneously, multiple Rspack configuration files will be generated in the `dist/.rsbuild` directory.
 
 ```bash
 ➜ npx rsbuild inspect
 
 Inspect config succeed, open following files to view the content:
 
-  - Rsbuild Config: /project/dist/rsbuild.config.mjs
-  - Rspack Config (web): /project/dist/rspack.config.web.mjs
-  - Rspack Config (node): /project/dist/rspack.config.node.mjs
+  - Rsbuild Config: /project/dist/.rsbuild/rsbuild.config.mjs
+  - Rspack Config (web): /project/dist/.rsbuild/rspack.config.web.mjs
+  - Rspack Config (node): /project/dist/.rsbuild/rspack.config.node.mjs
 ```

website/docs/en/guide/basic/configure-rsbuild.mdx

@@ -229,10 +229,10 @@ In debug mode, Rsbuild will write the Rsbuild config to the dist directory, whic
 ```
 Inspect config succeed, open the following files to view the content:
 
-   - Rsbuild Config: /Project/demo/dist/rsbuild.config.mjs
-   - Rspack Config (web): /Project/demo/dist/rspack.config.web.mjs
+   - Rsbuild Config: /Project/demo/dist/.rsbuild/rsbuild.config.mjs
+   - Rspack Config (web): /Project/demo/dist/.rsbuild/rspack.config.web.mjs
 ```
 
-Open the generated `/dist/rsbuild.config.mjs` file to see the complete content of the Rsbuild config.
+Open the generated `/dist/.rsbuild/rsbuild.config.mjs` file to see the complete content of the Rsbuild config.
 
 For a complete introduction to debug mode, see the [Debug Mode](/guide/debug/debug-mode) chapter.

website/docs/en/guide/debug/debug-mode.mdx

@@ -32,13 +32,13 @@ In addition, the following logs will be output in the terminal, indicating that
 ```bash
 Inspect config succeeds, open following files to view the content:
 
-   - Rsbuild Config: /Project/demo/dist/rsbuild.config.mjs
-   - Rspack Config (web): /Project/demo/dist/rspack.config.web.mjs
+   - Rsbuild Config: /Project/demo/dist/.rsbuild/rsbuild.config.mjs
+   - Rspack Config (web): /Project/demo/dist/.rsbuild/rspack.config.web.mjs
 ```
 
 ## Rsbuild Config File
 
-In debug mode, Rsbuild will automatically generate `dist/rsbuild.config.mjs` file, which contains the final generated Rsbuild config. In this file, you can know the final result of the Rsbuild config you passed in after being processed by the framework and Rsbuild.
+In debug mode, Rsbuild will automatically generate `dist/.rsbuild/rsbuild.config.mjs` file, which contains the final generated Rsbuild config. In this file, you can know the final result of the Rsbuild config you passed in after being processed by the framework and Rsbuild.
 
 The structure of the file is as follows:
 
@@ -58,7 +58,7 @@ For a complete introduction to Rsbuild config, please see the [Configure Rsbuild
 
 ## Rspack Config File
 
-Rsbuild will also automatically generate `dist/rspack.config.web.mjs` file, which contains the final generated Rspack config. In this file, you can see what is included in the config that Rsbuild finally passes to Rspack.
+Rsbuild will also automatically generate `dist/.rsbuild/rspack.config.web.mjs` file, which contains the final generated Rspack config. In this file, you can see what is included in the config that Rsbuild finally passes to Rspack.
 
 The structure of the file is as follows:
 

website/docs/en/guide/faq/features.mdx

@@ -64,8 +64,8 @@ debug   add default plugins done [1938.57 ms]
 
 Inspect config succeed, open following files to view the content:
 
-  - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
-  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
+  - Rsbuild Config: /root/my-project/dist/.rsbuild/rsbuild.config.mjs
+  - Rspack Config (web): /root/my-project/dist/.rsbuild/rspack.config.web.mjs
 ```
 
 ---

website/docs/zh/guide/advanced/environments.mdx

@@ -74,10 +74,10 @@ export default {
 
 Inspect config succeed, open following files to view the content:
 
-  - Rsbuild Config (web): /project/dist/rsbuild.config.web.mjs
-  - Rsbuild Config (node): /project/dist/rsbuild.config.node.mjs
-  - Rspack Config (web): /project/dist/rspack.config.web.mjs
-  - Rspack Config (node): /project/dist/rspack.config.node.mjs
+  - Rsbuild Config (web): /project/dist/.rsbuild/rsbuild.config.web.mjs
+  - Rsbuild Config (node): /project/dist/.rsbuild/rsbuild.config.node.mjs
+  - Rspack Config (web): /project/dist/.rsbuild/rspack.config.web.mjs
+  - Rspack Config (node): /project/dist/.rsbuild/rspack.config.node.mjs
 ```
 
 ## 默认 environment

website/docs/zh/guide/basic/cli.mdx

@@ -128,7 +128,7 @@ Options:
   -h, --help            显示命令帮助
 ```
 
-当你在项目根目录下执行命令 `npx rsbuild inspect` 后，会在项目的 `dist` 目录生成以下文件：
+当你在项目根目录下执行命令 `npx rsbuild inspect` 后，会在项目的 `dist/.rsbuild` 目录生成以下文件：
 
 - `rsbuild.config.mjs`: 表示在构建时使用的 Rsbuild 配置。
 - `rspack.config.web.mjs`: 表示在构建时使用的 Rspack 配置。
@@ -138,8 +138,8 @@ Options:
 
 Inspect config succeed, open following files to view the content:
 
-  - Rsbuild Config: /project/dist/rsbuild.config.mjs
-  - Rspack Config (web): /project/dist/rspack.config.web.mjs
+  - Rsbuild Config: /project/dist/.rsbuild/rsbuild.config.mjs
+  - Rspack Config (web): /project/dist/.rsbuild/rspack.config.web.mjs
 ```
 
 ### 指定模式
@@ -160,14 +160,14 @@ rsbuild inspect --verbose
 
 ### 多种产物类型
 
-如果当前项目有多种产物类型，比如同时构建了浏览器产物和 Node.js 产物，那么会在 `dist` 目录生成多份 Rspack 配置文件。
+如果当前项目有多种产物类型，比如同时构建了浏览器产物和 Node.js 产物，那么会在 `dist/.rsbuild` 目录生成多份 Rspack 配置文件。
 
 ```bash
 ➜ npx rsbuild inspect
 
 Inspect config succeed, open following files to view the content:
 
-  - Rsbuild Config: /project/dist/rsbuild.config.mjs
-  - Rspack Config (web): /project/dist/rspack.config.web.mjs
-  - Rspack Config (node): /project/dist/rspack.config.node.mjs
+  - Rsbuild Config: /project/dist/.rsbuild/rsbuild.config.mjs
+  - Rspack Config (web): /project/dist/.rsbuild/rspack.config.web.mjs
+  - Rspack Config (node): /project/dist/.rsbuild/rspack.config.node.mjs
 ```

website/docs/zh/guide/basic/configure-rsbuild.mdx

@@ -229,10 +229,10 @@ DEBUG=rsbuild pnpm dev
 ```
 Inspect config succeed, open following files to view the content:
 
-  - Rsbuild Config: /Project/demo/dist/rsbuild.config.mjs
-  - Rspack Config (web): /Project/demo/dist/rspack.config.web.mjs
+  - Rsbuild Config: /Project/demo/dist/.rsbuild/rsbuild.config.mjs
+  - Rspack Config (web): /Project/demo/dist/.rsbuild/rspack.config.web.mjs
 ```
 
-打开生成的 `/dist/rsbuild.config.mjs` 文件，即可查看 Rsbuild 配置的完整内容。
+打开生成的 `/dist/.rsbuild/rsbuild.config.mjs` 文件，即可查看 Rsbuild 配置的完整内容。
 
 关于调试模式的完整介绍，请查看 [开启调试模式](/guide/debug/debug-mode) 章节。