docs: add guide for get compilation object (#10501)

chenjiahan · web-flow · commit 35f1126963d5 · 2025-05-28T22:17:42.000+08:00
diff --git a/website/docs/en/api/javascript-api/compilation.mdx b/website/docs/en/api/javascript-api/compilation.mdx
@@ -30,6 +30,24 @@ In Rspack, the real compilation object runs on the Rust side, and the JavaScript
 Therefore, some complex data structures and methods will not be supported on the JavaScript compilation object, the data is **read-only** and the structure may differ from webpack.
 :::
 
+## Get compilation object
+
+You can get the current compilation object via [compiler.hooks.thisCompilation](/api/plugin-api/compiler-hooks#thiscompilation) or [compiler.hooks.compilation](/api/plugin-api/compiler-hooks#compilation) hooks.
+
+```js
+class ExamplePlugin {
+  apply(compiler) {
+    compiler.hooks.thisCompilation.tap('ExamplePlugin', compilation => {
+      console.log('thisCompilation hook called:', compilation);
+    });
+
+    compiler.hooks.compilation.tap('ExamplePlugin', compilation => {
+      console.log('compilation hook called:', compilation);
+    });
+  }
+}
+```
+
 ## Compilation methods
 
 ### emitAsset
diff --git a/website/docs/en/api/plugin-api/compiler-hooks.mdx b/website/docs/en/api/plugin-api/compiler-hooks.mdx
@@ -372,17 +372,19 @@ Executes a plugin after compilation parameters are created.
 
 ## `compile`
 
-Called right after `beforeCompile`, before a new compilation is created.
+Called right after `beforeCompile`, before a new [compilation object](/api/javascript-api/compilation) is created.
 
 - **Type:** `SyncHook<[]>`
 
 ## `thisCompilation`
 
-Called while initializing the compilation, right before calling the `compilation` hook.
+Called while initializing the compilation, can be used to get the current compilation object.
+
+You can use the `compilation` parameter to access the properties of the compilation object, or register [compilation hooks](/api/plugin-api/compilation-hooks).
 
 - **Type:** `SyncHook<[Compilation]>`
 - **Arguments:**
-  - `Compilation`: created [compilation](/api/javascript-api/compilation) object
+  - `compilation`: created [compilation](/api/javascript-api/compilation) object
 
 <Collapse>
   <CollapsePanel
@@ -394,13 +396,33 @@ Called while initializing the compilation, right before calling the `compilation
   </CollapsePanel>
 </Collapse>
 
+- **Example:**
+
+```js
+class ExamplePlugin {
+  apply(compiler) {
+    compiler.hooks.thisCompilation.tap('ExamplePlugin', compilation => {
+      console.log('compilation created:', compilation);
+
+      compilation.hooks.make.tap('ExamplePlugin', compilation => {
+        console.log("compilation's make hook called:", compilation);
+      });
+    });
+  }
+}
+```
+
 ## `compilation`
 
-Runs a plugin after a compilation has been created.
+Called after the compilation object is created, can be used to get the current compilation object.
+
+You can use the `compilation` parameter to access the properties of the compilation object, or register [compilation hooks](/api/plugin-api/compilation-hooks).
+
+`compilation` hook is called after the [thisCompilation](#thiscompilation) hook, and `thisCompilation` hook is not copied to child compiler, while `compilation` hook is copied to child compiler.
 
 - **Type:** `SyncHook<[Compilation]>`
 - **Arguments:**
-  - `Compilation`: created [compilation](/api/javascript-api/compilation) object
+  - `compilation`: created [compilation](/api/javascript-api/compilation) object
 
 <Collapse>
   <CollapsePanel
@@ -412,6 +434,20 @@ Runs a plugin after a compilation has been created.
   </CollapsePanel>
 </Collapse>
 
+```js
+class ExamplePlugin {
+  apply(compiler) {
+    compiler.hooks.compilation.tap('ExamplePlugin', compilation => {
+      console.log('compilation created:', compilation);
+
+      compilation.hooks.make.tap('ExamplePlugin', compilation => {
+        console.log("compilation's make hook called:", compilation);
+      });
+    });
+  }
+}
+```
+
 ## `make`
 
 Called before the make phase.
diff --git a/website/docs/zh/api/javascript-api/compilation.mdx b/website/docs/zh/api/javascript-api/compilation.mdx
@@ -30,6 +30,24 @@ Compilation 对象是 Rspack 构建过程中的核心对象之一，每当 Rspac
 因此，部分较为复杂的数据结构和方法将不会在 JavaScript Compilation 上支持，同时**数据只读**且结构可能与 webpack 存在差异。
 :::
 
+## 获取 compilation 对象
+
+你可以通过 [compiler.hooks.thisCompilation](/api/plugin-api/compiler-hooks#thiscompilation) 或 [compiler.hooks.compilation](/api/plugin-api/compiler-hooks#compilation) 钩子来获取当前的 compilation 对象。
+
+```js
+class ExamplePlugin {
+  apply(compiler) {
+    compiler.hooks.thisCompilation.tap('ExamplePlugin', compilation => {
+      console.log('thisCompilation hook called:', compilation);
+    });
+
+    compiler.hooks.compilation.tap('ExamplePlugin', compilation => {
+      console.log('compilation hook called:', compilation);
+    });
+  }
+}
+```
+
 ## Compilation 对象方法
 
 ### emitAsset
diff --git a/website/docs/zh/api/plugin-api/compiler-hooks.mdx b/website/docs/zh/api/plugin-api/compiler-hooks.mdx
@@ -367,17 +367,19 @@ class ExamplePlugin {
 
 ## `compile`
 
-在一个新的 compilation 创建之前调用。
+在一个新的 [compilation 对象](/api/javascript-api/compilation) 被创建之前调用。
 
 - **类型：** `SyncHook<[]>`
 
 ## `thisCompilation`
 
-创建 compilation 时调用，在触发 compilation 钩子之前调用。
+在创建 compilation 对象时调用，用于获取当前的 compilation 对象。
+
+你可以通过 `compilation` 参数来访问 compilation 对象的属性，或是注册 [compilation hooks](/api/plugin-api/compilation-hooks)。
 
 - **类型：** `SyncHook<[Compilation]>`
 - **参数：**
-  - `Compilation`: 创建的 [Compilation](/api/javascript-api/compilation) 对象
+  - `compilation`: 创建的 [compilation 对象](/api/javascript-api/compilation)
 
 <Collapse>
   <CollapsePanel
@@ -389,13 +391,33 @@ class ExamplePlugin {
   </CollapsePanel>
 </Collapse>
 
+- **示例：**
+
+```js
+class ExamplePlugin {
+  apply(compiler) {
+    compiler.hooks.thisCompilation.tap('ExamplePlugin', compilation => {
+      console.log('compilation created:', compilation);
+
+      compilation.hooks.make.tap('ExamplePlugin', compilation => {
+        console.log("compilation's make hook called:", compilation);
+      });
+    });
+  }
+}
+```
+
 ## `compilation`
 
-compilation 创建之后执行。
+在 compilation 对象创建之后调用，用于获取当前的 compilation 对象。
+
+你可以使用 `compilation` 参数来访问 compilation 对象的属性，或是注册 [compilation hooks](/api/plugin-api/compilation-hooks)。
+
+`compilation` 钩子的调用晚于 [thisCompilation](#thiscompilation) 钩子，并且 `thisCompilation` 钩子不会被复制到 child compiler 中，而 `compilation` 钩子会被复制到 child compiler 中。
 
 - **类型：** `SyncHook<[Compilation]>`
 - **参数：**
-  - `Compilation`: 创建的 [Compilation](/api/javascript-api/compilation) 对象
+  - `compilation`: 创建的 [compilation](/api/javascript-api/compilation) 对象
 
 <Collapse>
   <CollapsePanel
@@ -406,6 +428,21 @@ compilation 创建之后执行。
     <CompilationType />
   </CollapsePanel>
 </Collapse>
+
+```js
+class ExamplePlugin {
+  apply(compiler) {
+    compiler.hooks.compilation.tap('ExamplePlugin', compilation => {
+      console.log('compilation created:', compilation);
+
+      compilation.hooks.make.tap('ExamplePlugin', compilation => {
+        console.log("compilation's make hook called:", compilation);
+      });
+    });
+  }
+}
+```
+
 ## `make`
 
 在 make 阶段开始前调用，在 make 阶段会以 entry 为起点构建模块依赖图，并使用 loader 处理各个模块。
diff --git a/website/rspress.config.ts b/website/rspress.config.ts
@@ -177,6 +177,8 @@ export default defineConfig({
     ],
     source: {
       preEntry: ['./theme/tailwind.css'],
+    },
+    resolve: {
       alias: {
         '@builtIns': path.join(__dirname, 'components', 'builtIns'),
         '@components': path.join(__dirname, 'components'),
