Create a diagram showing hook lifecycle

[jakearchibald]

Documentation Is:

• Missing
• Needed
• Confusing
• Not Sure?

Please Explain in Detail...

Once the order of hooks is documented (#3409), create a diagram that provides an overview of the lifecycle.

Your Proposal for Changes

It isn't clear what type of diagram would be best, but hopefully that will be clearer once #3409 is resolved.

Update

by @lukastaegert:

Previous and next steps in the hooks are now documented on the website. @jakearchibald created a nice writeup which could be used to build a diagram upon here: #3418 (comment)

[shellscape]

@lukastaegert if you can put together a simple ascii diagram, I can translate that into something interactive and open a PR

[jakearchibald]

I have a vague worry that trying to create this diagram-first might encourage the wrong kind of diagram.

Instead, #3409 (which is useful on its own) will provide the data need to plan the diagram.

[lukastaegert]

I actually started on #3409, hope I can finish it soon (need to squeeze it in between other work at the moment)

[jakearchibald]

I listed the steps in order in #3418 (comment). It feels like it could be used to build a flow chart or something similar.

[yfwz100]

Can we add such a diagram to the documentation?

The notation [S] means sequential, [F] means first and [P] means parallel.
Which is generated from mermaid:

flowchart TB
    buildStart["[P] buildStart"]
	buildEnd["[P] buildEnd"]
	load["[F] load"]
	moduleParsed["[P] moduleParsed"]
	options["[S] options"]
	resolveDynamicImport["[F] resolveDynamicImport"]
	resolveId["[F] resolveId"]
	transform["[S] transform"]
    options-->buildStart-->|entry|resolveId-->|external|buildEnd
    resolveId-->load-->transform-->moduleParsed-->buildEnd
    moduleParsed-->resolveDynamicImport-->load
    moduleParsed-->resolveId
    resolveDynamicImport-->|external|buildEnd

[lukastaegert]

That looks really nice! Do you think there is a way to make the hooks clickable and link them to the documentation via mermaid?

[lukastaegert]

Ah, seems you can add some click handlers: https://mermaid-js.github.io/mermaid/#/flowchart?id=interaction
I think that is fabulous, we just need to integrate it with the build pipeline.

[yfwz100]

I've added link below but I'm new to rollup and need some time or someone to integrate it into the build pipeline. The diagram is drawn to learn the process of rollup. Having a diagram is helpful to understand how plugin works. :-)

Build hooks

flowchart TB
    buildStart["[P] buildStart"]
	buildEnd["[P] buildEnd"]
	load["[F] load"]
	moduleParsed["[P] moduleParsed"]
	options["[S] options"]
	resolveDynamicImport["[F] resolveDynamicImport"]
	resolveId["[F] resolveId"]
	transform["[S] transform"]
	click buildStart "https://rollupjs.org/guide/en/#buildstart"
	click buildEnd "https://rollupjs.org/guide/en/#buildend"
	click load "https://rollupjs.org/guide/en/#load"
	click moduleParsed "https://rollupjs.org/guide/en/#moduleparsed"
	click options "https://rollupjs.org/guide/en/#options"
	click resolveDynamicImport "https://rollupjs.org/guide/en/#resolvedynamicimport"
	click resolveId "https://rollupjs.org/guide/en/#resolveid"
	click transform "https://rollupjs.org/guide/en/#transform"
    options-->buildStart
    buildStart-->|entry|resolveId
    resolveId-->|external|buildEnd
    resolveId-->load
    load-->transform
    transform-->moduleParsed
    moduleParsed-->buildEnd
    moduleParsed-->resolveDynamicImport
    resolveDynamicImport-->load
    moduleParsed-->resolveId
    resolveDynamicImport-->|external|buildEnd

Output Generation Hooks

flowchart TB
	augmentChunkHash["[S] augmentChunkHash"]
	banner["[P] banner"]
	closeBundle["[P] closeBundle"]
	footer["[P] footer"]
	generateBundle["[S] generateBundle"]
	intro["[P] intro"]
	outputOptions["[S] outputOptions"]
	outro["[P] outro"]
	buildEnd-->|error|closeBundle
	buildEnd-->outputOptions
	renderChunk["[S] renderChunk"]
	renderDynamicImport["[F] renderDynamicImport"]
	renderStart["[P] renderStart"]
	resolveFileUrl["[F] resolveFileUrl"]
	resolveImportMeta["[F] resolveImportMeta"]
	writeBundle["[P] writeBundle"]
	click buildEnd "https://rollupjs.org/guide/en/#buildend"
	click augmentChunkHash "https://rollupjs.org/guide/en/#augmentchunkhash"
	click banner "https://rollupjs.org/guide/en/#banner"
	click footer "https://rollupjs.org/guide/en/#footer"
	click generateBundle "https://rollupjs.org/guide/en/#generatebundle"
	click intro "https://rollupjs.org/guide/en/#intro"
	click outputOptions "https://rollupjs.org/guide/en/#outputoptions"
	click outro "https://rollupjs.org/guide/en/#outro"
	click renderChunk "https://rollupjs.org/guide/en/#renderchunk"
	click renderDynamicImport "https://rollupjs.org/guide/en/#renderdynamicimport"
	click renderStart "https://rollupjs.org/guide/en/#renderstart"
	click resolveFileUrl "https://rollupjs.org/guide/en/#resolvefileurl"
	click resolveImportMeta "https://rollupjs.org/guide/en/#resolveimportmeta"
	click closeBundle "https://rollupjs.org/guide/en/#closebundle"
	click writeBundle "https://rollupjs.org/guide/en/#writebundle"
	augmentChunkHash-->resolveFileUrl
	augmentChunkHash-->resolveImportMeta
	banner-->renderDynamicImport
	footer-->renderDynamicImport
	generateBundle-->writeBundle
	intro-->renderDynamicImport
	outputOptions-->renderStart
	outro-->renderDynamicImport
	renderChunk-->generateBundle
	renderDynamicImport-->augmentChunkHash
	renderStart-->banner
	renderStart-->footer
	renderStart-->intro
	renderStart-->outro
	resolveFileUrl-->renderChunk
	resolveImportMeta-->renderChunk

[yfwz100]

I couldn't find the build scripts for docs. Are there anything I can start working with?

[lukastaegert]

It is slightly complicated. I actually started setting something up but will until tomorrow to be able to push it so that we can have a look. Most stuff is happening in the rollup/rollupjs.org repo while we also need to link the diagrams from the docs in the main repo.

[yfwz100]

Ok, if there're something I can help. I'm glad to do it. Hope to see the diagrams in the offical docs. :-)

[lukastaegert]

So it turned out this was much more involved than anticipated but here we go now: https://deploy-preview-230--rollup.netlify.app/guide/en/#build-hooks

It is now based on a comment syntax and placing files in the docs folder, see #4206 and rollup/rollupjs.org#230

[yfwz100]

Nice! It's more clear now.

[jakearchibald]

This is great! Couple of notes:

• It isn't clear what the difference is between lines and dotted lines
• It isn't clear where "each entry" ends. Currently it looks like buildEnd could happen per entry.
• moduleParsed has an 'each import' branch, should this be 'each unresolved import'?

[lukastaegert]

moduleParsed has an 'each import' branch, should this be 'each unresolved import'?

No, resolveId happens for all of them. Technically what does not happen necessarily is the load-transform steps if we already have this module. We could mention this as well.

It isn't clear where "each entry" ends. Currently it looks like buildEnd could happen per entry.

I was not sure how to write it without severely increasing complexity, but suggestions welcome. At the moment, an "each" usually ends at a dotted line.

It isn't clear what the difference is between lines and dotted lines

Roughly "if nothing else needs to be done here, we can eventually end up here". With that logic, I guess we need even more dotted lines in the output graph, i.e. for renderDynamicImport.

I am really open for suggestions. Luckily, Mermaid has a nice live editor where you can just copy and paste the code from here https://github.com/rollup/rollup/blob/master/docs/build-hooks.mmd to try out different things so that we can talk about it.