[Documentation] Plugin hook call order

[dhouck]

The Rspack documentation (compiler hooks, compilation hooks) shows several flowcharts of when the various hooks are called. This is a marked improvement over what Iʼve found in the Webpack documentation, which seems to just list the hooks without an expected order of operations, but it can still be confusing; Iʼm not sure Iʼm reading them correctly.

Some particular issues Iʼve noticed and been confused by:

• Iʼm not sure what the colors mean. It looks like blue is mostly the happy path and red isnʼt, but thatʼs not entirely correct. If I look at the source code, itʼs about “non-support”, but Iʼm not sure what that means; if itʼs about which Webpack hooks Rspack does/doesnʼt support, itʼs out of date since several of the red ones seem to be supported in the code. Also hooks.done is listed twice, and it canʼt be both supported and not if thatʼs what it means.
• Some arrows seem to be missing; the two Iʼve spotted are that thereʼs no false arrow for hooks.needAdditionalPass and no entry point for HookEmitRecords. Those are both “non-support”, so that might make sense, except that needsAdditionalPass is sometimes called, and surely, whether there are hooks for it or not, itʼs possible for the code to not need an additional pass.
• Iʼm not entirely sure I know when each chart is run. I think I mostly understand, but some of the hooks arenʼt called in the order I expect; I think this is a bug in the code and the documentation is correctly saying the expected behavior, but Iʼm not sure. Iʼll make an issue about that shorty.

Also, a documentation issue not related to the chart: it isnʼt explained what the various hook types are. I needed to go to the Webpack documentation to understand what they meant.

So, my questions:

• Is this the right place to mention confusing documentation, or should it be filed as an Issue (Feature Request) or something?
• What do the colors on the flowcharts mean?
• Where should the missing arrows come from/go?

[b84330808]

Discussions is fine for this, though the chart lives in website/docs/en/api/plugin-api/compiler-hooks.mdx, so a docs issue or PR against that file is probably the fastest way to get it fixed.

The colors come from website/components/Mermaid.scss. The grey boxes are start/end and internal steps, blue is flow-hook, and red is flow-hook-non-support. So red meant "webpack has this hook, Rspack doesn't call it". That list is stale, though. Tapping every compiler.hooks entry on @rspack/core 2.2.9 shows these red ones do fire: normalModuleFactory, contextModuleFactory, assetEmitted (once per file), additionalPass, and the extra done before an additional pass. readRecords and emitRecords don't exist on compiler.hooks at all.

On the missing arrows: in Rspack, needAdditionalPass is a compilation hook (compilation.hooks.needAdditionalPass), checked right after afterEmit. If it returns false, the next thing is compiler.hooks.done. If it returns true you get done → additionalPass → a full compile again, which is why done appears twice in the chart. HookEmitRecords has no entry because webpack's false branch goes emitRecords → done, and Rspack has no emitRecords, so that node is left over from the webpack chart.

For reference, compiler.run() goes:

beforeRun → run → normalModuleFactory → contextModuleFactory → beforeCompile → compile
→ thisCompilation → compilation → make → finishMake → afterCompile → shouldEmit → emit
→ assetEmitted (per file) → afterEmit → compilation.needAdditionalPass → done → callback → afterDone

watch() is the same except watchRun replaces beforeRun/run, and watchClose fires on watching.close().

(I used Claude Code to check this.)