Skip to content

Commit ec9322f

Browse files
author
Pavithra K
committed
Adds plugin type info and event list for compiler
1 parent 02c2f48 commit ec9322f

File tree

2 files changed

+78
-49
lines changed

2 files changed

+78
-49
lines changed

‎content/pluginsapi/compiler.md

Lines changed: 32 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ compiler.options = {...};
2525
class LogPlugin {
2626
apply (compiler) {
2727
compiler.plugin('should-emit', compilation => {
28-
console.log('should i emit');
28+
console.log('should i emit?');
2929
return true;
3030
})
3131
}
@@ -47,7 +47,7 @@ compiler.run(callback);
4747
```
4848

4949
The `Compiler` is what we call a `Tapable` instance. By this, we mean that it mixes in `Tapable` class to imbibe functionality to register and call plugins on itself.
50-
All user facing plugins are first registered on the `Compiler`.
50+
Most user facing plugins are first registered on the `Compiler`.
5151
The working of a Compiler can be condensed into the following highlights
5252
- Usually there is one master instance of Compiler. Child compilers can be created for delegating specific tasks.
5353
- A lot of the complexity in creating a compiler goes into populating all the relevant options for it.
@@ -59,7 +59,7 @@ The working of a Compiler can be condensed into the following highlights
5959
## Watching
6060

6161
However, the `Compiler` supports two flavors of execution. One on watch mode and one on a normal single run.
62-
While it essentially performs the same functionality while watching, there are some subtle changes to the lifecycle events. This allows `webpack` to have Watch specific plugins.
62+
While it essentially performs the same functionality while watching, there are some additions to the lifecycle events. This allows `webpack` to have Watch specific plugins.
6363

6464
## MultiCompiler
6565

@@ -69,48 +69,32 @@ While it essentially performs the same functionality while watching, there are s
6969

7070
This a reference guide to all the event hooks exposed by the `Compiler`.
7171

72-
?>TODO: For each hook follow template of
73-
1. event name
74-
2. reason for event.
75-
3. async or sync or parallel or waterfall
76-
4. some usage examples.
77-
78-
`environment()`
79-
80-
`after-environment()`
81-
82-
`before-run(compiler: Compiler, callback)`
83-
84-
`run(callback)`
85-
86-
`watch-run(watching: Watching, callback)`
87-
88-
`normal-module-factory(normalModuleFactory: NormalModuleFactory)`
89-
90-
`context-module-factory(contextModuleFactory: ContextModuleFactory)`
91-
92-
`compilation(compilation: Compilation, params: Object)`
93-
94-
`this-compilation(compilation: Compilation, params: Object)`
95-
96-
`after-plugins(compiler: Compiler)`
97-
98-
`after-resolvers(compiler: Compiler)`
99-
100-
`should-emit(compilation: Compilation)`
101-
102-
`emit(compilation: Compilation, callback)`
103-
104-
`after-emit(compilation: Compilation, callback)`
105-
106-
`done(stats: Stats)`
107-
108-
`additional-pass(callback)`
109-
110-
`failed(err: Error)`
111-
112-
`invalid(fileName: string, changeTime)`
113-
114-
`entry-option(context, entry)`
115-
116-
## Examples
72+
| Event name | Reason | Params | Type |
73+
|----------------------------|-------------------------------------|----------------------|------------|
74+
| __`entry-option`__ | - | - | bailResult |
75+
| __`after-plugins`__ | After setting up initial set of plugins | `compiler` | sync |
76+
| __`after-resolvers`__ | After setting up the resolvers | `compiler` | sync |
77+
| __`environment`__ | - | - | sync |
78+
| __`after-environment`__ | Environment setup complete | - | sync |
79+
| __`before-run`__ | `compiler.run()` starts | `compiler` | async |
80+
| __`run`__ | Before reading records | `compiler` | async |
81+
| __`watch-run`__ | Before starting compilation after watch | `compiler` | async |
82+
| __`normal-module-factory`__ | After creating a `NormalModuleFactory` | `normalModuleFactory`| sync |
83+
| __`context-module-factory`__ | After creating a `ContextModuleFactory` | `contextModuleFactory`| sync |
84+
| __`before-compile`__ | Compilation parameters created | `compilationParams`` | sync |
85+
| __`compile`__ | Before creating new compilation | `compilationParams` | sync |
86+
| __`this-compilation`__ | Before emitting `compilation` event | `compilation` | sync |
87+
| __`compilation`__ | Compilation creation completed | `compilation` | sync |
88+
| __`make`__ | | `compilation` | parallel |
89+
| __`after-compile`__ | | `compilation` | async |
90+
| __`should-emit`__ | Can return true/false at this point | `compilation` | bailResult |
91+
| __`need-additional-pass`__ | | - | bailResult |
92+
| __`emit`__ | Before writing emitted assets to output dir | `compilation` | async |
93+
| __`after-emit`__ | After writing emitted assets to output dir | `compilation` | async |
94+
| __`done`__ | Completion of compile | `stats` | sync |
95+
| __`fail`__ | Failure of compile | `error` | sync |
96+
| __`invalid`__ | After invalidating a watch compile | `fileName`, `changeTime` | sync |
97+
98+
## Examples
99+
100+
?> TODO: Adds examples of usage for some of the above events

‎content/pluginsapi/index.md

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,4 +43,49 @@ MyExampleWebpackPlugin.prototype.apply = function(compiler) {
4343
};
4444
```
4545

46-
### Different Plugin Shapes
46+
### Different Plugin Shapes
47+
48+
A plugin can be classified into types based on the event it is registered to. Every event hook decides how it is going to apply the plugins in its registry.
49+
50+
- __synchronous__ The Tapable instance applies plugins using
51+
52+
`applyPlugins(name: string, args: any...)`
53+
54+
`applyPluginsBailResult(name: string, args: any...)`
55+
56+
This means that each of the plugin callbacks will be invoked one after the other with the specific `args`.
57+
This is the simplest format for a plugin. Many useful events like `"compile"`, `"this-compilation"` expect plugins to have synchronous execution.
58+
59+
- __waterfall__ Plugins applied using
60+
61+
`applyPluginsWaterfall(name: string, init: any, args: any...)`
62+
63+
Here each of the plugins are called one after the other with the args from the return value of the previous plugin. The plugin must take into consider the order of its execution.
64+
It must accept arguments from the previous plugin that was executed. The value for the first plugin is `init`. This pattern is used in the Tapable instances which are related to the `webpack` templates like `ModuleTemplate`, `ChunkTemplate` etc.
65+
66+
- __asynchronous__ When all the plugins are applied asynchronously using
67+
68+
`applyPluginsAsync(name: string, args: any..., callback: (err?: Error) -> void)`
69+
70+
The plugin handler functions are called with all args and a callback function with the signature `(err?: Error) -> void`. The hander functions are called in order of registration.`callback` is called after all the handlers are called.
71+
This is also a commonly used pattern for events like `"emit"`, `"run"`.
72+
73+
- __async waterfall__ The plugins will be applied asynchronously in the waterfall manner.
74+
75+
`applyPluginsAsyncWaterfall(name: string, init: any, callback: (err: Error, result: any) -> void)`
76+
77+
The plugin handler functions are called with the current value and a callback function with the signature `(err: Error, nextValue: any) -> void.` When called `nextValue` is the current value for the next handler. The current value for the first handler is `init`. After all handlers are applied, callback is called with the last value. If any handler passes a value for `err`, the callback is called with this error and no more handlers are called.
78+
This plugin pattern is expected for events like `"before-resolve"` and `"after-resolve"`.
79+
80+
- __async series__ It is the same as asynchronous but if any of the plugins registered fails, then no more plugins are called.
81+
82+
`applyPluginsAsyncSeries(name: string, args: any..., callback: (err: Error, result: any) -> void)`
83+
84+
-__parallel__ -
85+
86+
`applyPluginsParallel(name: string, args: any..., callback: (err?: Error) -> void)`
87+
88+
`applyPluginsParallelBailResult(name: string, args: any..., callback: (err: Error, result: any) -> void)`
89+
90+
91+

0 commit comments

Comments
 (0)