docs: update compiler hooks (#7366)

web-infra-dev · Jul 31, 2024 · 6a5343d · 6a5343d
1 parent 9e2cbe9
commit 6a5343d
Show file tree

Hide file tree

Showing 6 changed files with 353 additions and 193 deletions.
diff --git a/website/docs/en/api/objects/compilation.mdx b/website/docs/en/api/objects/compilation.mdx
@@ -10,7 +10,7 @@ import PathDataType from '../../types/path-data.mdx';
 import StatsType from '../../types/stats.mdx';
 import LoggerType from '../../types/logger.mdx';
 import CacheType from '../../types/cache.mdx';
-import CompilerType from '../../types/cache.mdx';
+import CompilerType from '../../types/compiler.mdx';
 import RspackErrorType from '../../types/rspack-error.mdx';
 import CompilationDependenciesType from '../../types/compilation-dependencies.mdx';
 import { Collapse, CollapsePanel } from '@components/Collapse';

diff --git a/website/docs/en/api/plugin-api/compiler-hooks.mdx b/website/docs/en/api/plugin-api/compiler-hooks.mdx
@@ -1,27 +1,40 @@
 import CompilerType from '../../types/compiler.mdx';
+import CompilationType from '../../types/compilation.mdx';
 import StatsType from '../../types/stats.mdx';
 import { Collapse, CollapsePanel } from '@components/Collapse';
+import { ApiMeta } from '@components/ApiMeta';
 
 # Compiler Hooks
 
 ## `environment`
 
-`SyncHook<[]>`
-
 Called while preparing the compiler environment, right after initializing the plugins in the configuration file.
 
+- **Type:** `SyncHook<[]>`
+
 ## `afterEnvironment`
 
-`SyncHook<[]>`
+Called right after the `environment` hook, when the compiler environment setup is complete.
 
-Called right after the environment hook, when the compiler environment setup is complete.
+- **Type:** `SyncHook<[]>`
 
-## `afterPlugins`
+## `entryOption`
+
+Called after the [`entry`](/config/entry) configuration from Rspack options has been processed.
 
-`SyncHook<[Compiler]>`
+- **Type:** `SyncBailHook<[string, EntryNormalized]>`
+- **Arguments:**
+  - `string`: same with [`context`](/config/context)
+  - `EntryNormalized`: normalized [`entry`](/config/entry)
+
+## `afterPlugins`
 
 Called after setting up initial set of internal plugins.
 
+- **Type:** `SyncHook<[Compiler]>`
+- **Arguments:**
+  - `Compiler`: current compiler instance
+
 <Collapse>
   <CollapsePanel
     className="collapse-code-panel"
@@ -34,10 +47,12 @@ Called after setting up initial set of internal plugins.
 
 ## `afterResolvers`
 
-`SyncHook<[Compiler]>`
-
 Triggered after resolver setup is complete.
 
+- **Type:** `SyncHook<[Compiler]>`
+- **Arguments:**
+  - `Compiler`: current compiler instance
+
 <Collapse>
   <CollapsePanel
     className="collapse-code-panel"
@@ -48,45 +63,19 @@ Triggered after resolver setup is complete.
   </CollapsePanel>
 </Collapse>
 
-## `entryOption`
-
-`SyncBailHook<[string, EntryNormalized]>`
-
-Called after the entry configuration has been processed.
-
-<Collapse>
-  <CollapsePanel header="EntryNormalized.ts" key="EntryNormalized">
-    See [entry configuration](/config/entry) for more details.
-  </CollapsePanel>
-</Collapse>
-
 ## `initialize`
 
-`SyncHook<[]>`
-
 Called when a compiler object is initialized.
 
-## `beforeRun`
+- **Type:** `SyncHook<[]>`
 
-`AsyncSeriesHook<[Compiler]>`
+## `beforeRun`
 
 Adds a hook right before running the compiler.
 
-<Collapse>
-  <CollapsePanel
-    className="collapse-code-panel"
-    header="Compiler.ts"
-    key="Compiler"
-  >
-    <CompilerType />
-  </CollapsePanel>
-</Collapse>
-
-## `run`
-
-`AsyncSeriesHook<[Compiler]>`
-
-Called at the beginning of a build execution.
+- **Type:** `AsyncSeriesHook<[Compiler]>`
+- **Arguments:**
+  - `Compiler`: current compiler instance
 
 <Collapse>
   <CollapsePanel
@@ -98,13 +87,13 @@ Called at the beginning of a build execution.
   </CollapsePanel>
 </Collapse>
 
-## `childCompiler`
-
-`SyncHook[Compiler, string, number]`
+## `run`
 
-> where the version of the function type is `>=0.4.1`.
+Called ad the beginning of a build execution.
 
-Executed after created a childCompiler.
+- **Type:** `AsyncSeriesHook<[Compiler]>`
+- **Arguments:**
+  - `Compiler`: current compiler instance
 
 <Collapse>
   <CollapsePanel
@@ -118,10 +107,12 @@ Executed after created a childCompiler.
 
 ## `watchRun`
 
-`AsyncSeriesHook<[Compiler]>`
-
 Executes a plugin during watch mode after a new compilation is triggered but before the compilation is actually started.
 
+- **Type:** `AsyncSeriesHook<[Compiler]>`
+- **Arguments:**
+  - `Compiler`: current compiler instance
+
 <Collapse>
   <CollapsePanel
     className="collapse-code-panel"
@@ -132,109 +123,157 @@ Executes a plugin during watch mode after a new compilation is triggered but bef
   </CollapsePanel>
 </Collapse>
 
-## `compile`
+## `beforeCompile`
 
-`SyncHook<[]>`
+Executes a plugin after compilation parameters are created.
 
-Called right after beforeCompile, before a new compilation is created.
+- **Type:** `AsyncSeriesHook<[]>`
 
-## `beforeCompile`
+## `compile`
 
-`AsyncSeriesHook<[]>`
+Called right after `beforeCompile`, before a new compilation is created.
 
-Executes a plugin after compilation parameters are created.
+- **Type:** `SyncHook<[]>`
 
-## `afterCompile`
+## `thisCompilation`
 
-`AsyncSeriesHook<[Compilation]>`
+Called while initializing the compilation, right before calling the `compilation` hook.
 
-Called after finishing and sealing the compilation.
+- **Type:** `SyncHook<[Compilation]>`
+- **Arguments:**
+  - `Compilation`: created [compilation](/api/objects/compilation) object
 
 <Collapse>
-  <CollapsePanel header="Compilation.ts" key="Compilation">
-    See [compilation object](/api/objects/compilation) for more details.
+  <CollapsePanel
+    className="collapse-code-panel"
+    header="Compilation.ts"
+    key="Compilation"
+  >
+    <CompilationType />
   </CollapsePanel>
 </Collapse>
 
-## `thisCompilation`
+## `compilation`
 
-`SyncHook<[Compilation]>`
+Runs a plugin after a compilation has been created.
 
-Executed while initializing the compilation, right before emitting the compilation event.
+- **Type:** `SyncHook<[Compilation]>`
+- **Arguments:**
+  - `Compilation`: created [compilation](/api/objects/compilation) object
 
 <Collapse>
-  <CollapsePanel header="Compilation.ts" key="Compilation">
-    See [compilation object](/api/objects/compilation) for more details.
+  <CollapsePanel
+    className="collapse-code-panel"
+    header="Compilation.ts"
+    key="Compilation"
+  >
+    <CompilationType />
   </CollapsePanel>
 </Collapse>
 
-## `compilation`
+## `make`
 
-`SyncHook<[Compilation]>`
+Called before the make phase.
 
-Runs a plugin after a compilation has been created.
+In the make phase, Rspack will build the module graph starting from the entry, and use the loader to handle each module.
+
+- **Type:** `AsyncParallelHook<[Compilation]>`
+- **Arguments:**
+  - `Compilation`: current [compilation](/api/objects/compilation) object
 
 <Collapse>
-  <CollapsePanel header="Compilation.ts" key="Compilation">
-    See [compilation object](/api/objects/compilation) for more details.
+  <CollapsePanel
+    className="collapse-code-panel"
+    header="Compilation.ts"
+    key="Compilation"
+  >
+    <CompilationType />
   </CollapsePanel>
 </Collapse>
 
-## `make`
+## `afterCompile`
 
-`AsyncParallelHook<[Compilation]>`
+Called after the make phase and before the seal phase.
 
-Executed before the make stage.
+In the seal phase, Rspack will create chunk graph from the module graph and then generate the assets.
+
+- **Type:** `AsyncSeriesHook<[Compilation]>`
+- **Arguments:**
+  - `Compilation`: current [compilation](/api/objects/compilation) object
 
 <Collapse>
-  <CollapsePanel header="Compilation.ts" key="Compilation">
-    See [compilation object](/api/objects/compilation) for more details.
+  <CollapsePanel
+    className="collapse-code-panel"
+    header="Compilation.ts"
+    key="Compilation"
+  >
+    <CompilationType />
   </CollapsePanel>
 </Collapse>
 
 ## `shouldEmit`
 
-`SyncBailHook<[Compilation]>`
+<ApiMeta addedVersion="0.4.1" />
 
-> where the version of the function type is `>=0.4.1`.
+Called before emitting assets. Should return a boolean telling whether to emit.
 
-Return a boolean telling whether to emit.
+- **Type:** `SyncBailHook<[Compilation]>`
+- **Arguments:**
+  - `Compilation`: current [compilation](/api/objects/compilation) object
 
 <Collapse>
-  <CollapsePanel header="Compilation.ts" key="Compilation">
-    See [compilation object](/api/objects/compilation) for more details.
+  <CollapsePanel
+    className="collapse-code-panel"
+    header="Compilation.ts"
+    key="Compilation"
+  >
+    <CompilationType />
   </CollapsePanel>
 </Collapse>
 
 ## `emit`
 
-`AsyncSeriesHook<[Compilation]>`
+Called right before emitting assets to output dir.
 
-Executed right before emitting assets to output directory.
+- **Type:** `AsyncSeriesHook<[Compilation]>`
+- **Arguments:**
+  - `Compilation`: current [compilation](/api/objects/compilation) object
 
 <Collapse>
-  <CollapsePanel header="Compilation.ts" key="Compilation">
-    See [compilation object](/api/objects/compilation) for more details.
+  <CollapsePanel
+    className="collapse-code-panel"
+    header="Compilation.ts"
+    key="Compilation"
+  >
+    <CompilationType />
   </CollapsePanel>
 </Collapse>
 
 ## `afterEmit`
 
-`AsyncSeriesHook<[Compilation]>`
-
 Called after emitting assets to output directory.
 
+- **Type:** `AsyncSeriesHook<[Compilation]>`
+- **Arguments:**
+  - `Compilation`: current [compilation](/api/objects/compilation) object
+
 <Collapse>
-  <CollapsePanel header="Compilation.ts" key="Compilation">
-    See [compilation object](/api/objects/compilation) for more details.
+  <CollapsePanel
+    className="collapse-code-panel"
+    header="Compilation.ts"
+    key="Compilation"
+  >
+    <CompilationType />
   </CollapsePanel>
 </Collapse>
 
 ## `done`
 
-`AsyncSeriesHook<Stats>`
+Called when the compilation has completed.
 
-Executed when the compilation has completed.
+- **Type:** `AsyncSeriesHook<Stats>`
+- **Arguments:**
+  - `Stats`: generated stats object
 
 <Collapse>
   <CollapsePanel className="collapse-code-panel" header="Stats.ts" key="Stats">
@@ -244,24 +283,26 @@ Executed when the compilation has completed.
 
 ## `afterDone`
 
-`AsyncSeriesHook<Stats>`
+Called after `done` hook.
 
-Executed after `done` hook.
+- **Type:** `SyncHook<Stats>`
+- **Arguments:**
+  - `Stats`: generated stats object
 
 <Collapse>
   <CollapsePanel className="collapse-code-panel" header="Stats.ts" key="Stats">
     <StatsType />
   </CollapsePanel>
 </Collapse>
 
-## `watchClose`
+## `failed`
 
-`SyncHook<[]>`
+Called if the compilation fails.
 
-Called when a watching compilation has stopped.
+- **Type:** `SyncHook<[Error]>`
 
-## `failed`
+## `watchClose`
 
-`SyncHook<[Error]>`
+Called when a watching compilation has stopped.
 
-Called if the compilation fails.
+- **Type:** `SyncHook<[]>`