Skip to content

Commit c0db521

Browse files
committed
docs(api): clarify the pitch method and how it can be used in loaders.md
Resolves #449 Resolves webpack#116 Refactored and enhanced the existing section using much of @sokra's explanation from: webpack/webpack#360
1 parent d6dee86 commit c0db521

File tree

1 file changed

+48
-6
lines changed

1 file changed

+48
-6
lines changed

src/content/api/loaders.md

+48-6
Original file line numberDiff line numberDiff line change
@@ -90,24 +90,66 @@ module.exports.raw = true;
9090

9191
### Pitching Loader
9292

93-
Loaders are **always** called from right to left. But, in some cases, loaders do not care about the results of the previous loader or the resource. They only care about **metadata**. The `pitch` method on the loaders is called from **left to right** before the loaders are called (from right to left).
93+
Loaders are __always__ called from right to left. There are some instances where the loader only cares about the __metadata__ behind a request and can ignore the results of the previous loader. The `pitch` method on loaders is called from __left to right__ before the loaders are actually executed (from right to left). For the following [`use`](/configuration/module#rule-use) configuration:
9494

95-
If a loader delivers a result in the `pitch` method the process turns around and skips the remaining loaders, continuing with the calls to the more left loaders. `data` can be passed between pitch and normal call.
95+
``` js
96+
use: [
97+
'a-loader',
98+
'b-loader',
99+
'c-loader'
100+
]
101+
```
102+
103+
These steps would occur:
104+
105+
``` diff
106+
|- a-loader `pitch`
107+
|- b-loader `pitch`
108+
|- c-loader `pitch`
109+
|- requested module is picked up as a dependency
110+
|- c-loader normal execution
111+
|- b-loader normal execution
112+
|- a-loader normal execution
113+
```
114+
115+
So why might a loader take advantage of the "pitching" phase?
116+
117+
First, the `data` passed to the `pitch` method is exposed in the execution phase as well under `this.data` and could be useful for capturing and sharing information from earlier in the cycle.
96118

97119
``` js
98120
module.exports = function(content) {
99121
return someSyncOperation(content, this.data.value);
100122
};
101123

102124
module.exports.pitch = function(remainingRequest, precedingRequest, data) {
103-
if(someCondition()) {
104-
// fast exit
105-
return "module.exports = require(" + JSON.stringify("-!" + remainingRequest) + ");";
106-
}
107125
data.value = 42;
108126
};
109127
```
110128

129+
Second, if a loader delivers a result in the `pitch` method the process turns around and skips the remaining loaders. In our example above, if the `b-loader`s `pitch` method returned something:
130+
131+
``` js
132+
module.exports = function(content) {
133+
return someSyncOperation(content);
134+
};
135+
136+
module.exports.pitch = function(remainingRequest, precedingRequest, data) {
137+
if (someCondition()) {
138+
return "module.exports = require(" + JSON.stringify("-!" + remainingRequest) + ");";
139+
}
140+
};
141+
```
142+
143+
The steps above would be shortened to:
144+
145+
``` diff
146+
|- a-loader `pitch`
147+
|- b-loader `pitch` returns a module
148+
|- a-loader normal execution
149+
```
150+
151+
See the [bundle-loader](https://github.com/webpack-contrib/bundle-loader) for a good example of how this process can be used in a more meaningful way.
152+
111153

112154
## The Loader Context
113155

0 commit comments

Comments
 (0)