Skip to content

Commit 29ce0ef

Browse files
mc-zonemontogeek
authored andcommitted
docs(API) Add error report introduction of loaders (#2231) (#2298)
These additions resolve #2231 .
1 parent db50ffb commit 29ce0ef

File tree

1 file changed

+108
-14
lines changed

1 file changed

+108
-14
lines changed

src/content/api/loaders.md

Lines changed: 108 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Either `return` or `this.callback` can be used to return the transformed `conten
2525

2626
__sync-loader.js__
2727

28-
``` js
28+
``` javascript
2929
module.exports = function(content, map, meta) {
3030
return someSyncOperation(content);
3131
};
@@ -35,7 +35,7 @@ The `this.callback` method is more flexible as it allows multiple arguments to b
3535

3636
__sync-loader-with-multiple-results.js__
3737

38-
``` js
38+
``` javascript
3939
module.exports = function(content, map, meta) {
4040
this.callback(null, someSyncOperation(content), map, meta);
4141
return; // always return undefined when calling callback()
@@ -48,7 +48,7 @@ For asynchronous loaders, [`this.async`](/api/loaders#this-async) is used to ret
4848

4949
__async-loader.js__
5050

51-
``` js
51+
``` javascript
5252
module.exports = function(content, map, meta) {
5353
var callback = this.async();
5454
someAsyncOperation(content, function(err, result) {
@@ -60,7 +60,7 @@ module.exports = function(content, map, meta) {
6060

6161
__async-loader-with-multiple-results.js__
6262

63-
``` js
63+
``` javascript
6464
module.exports = function(content, map, meta) {
6565
var callback = this.async();
6666
someAsyncOperation(content, function(err, result, sourceMaps, meta) {
@@ -79,7 +79,7 @@ By default, the resource file is converted to a UTF-8 string and passed to the l
7979

8080
__raw-loader.js__
8181

82-
``` js
82+
``` javascript
8383
module.exports = function(content) {
8484
assert(content instanceof Buffer);
8585
return someSyncOperation(content);
@@ -94,7 +94,7 @@ module.exports.raw = true;
9494

9595
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:
9696

97-
``` js
97+
``` javascript
9898
module.exports = {
9999
//...
100100
module: {
@@ -128,7 +128,7 @@ So why might a loader take advantage of the "pitching" phase?
128128

129129
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.
130130

131-
``` js
131+
``` javascript
132132
module.exports = function(content) {
133133
return someSyncOperation(content, this.data.value);
134134
};
@@ -140,7 +140,7 @@ module.exports.pitch = function(remainingRequest, precedingRequest, data) {
140140

141141
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:
142142

143-
``` js
143+
``` javascript
144144
module.exports = function(content) {
145145
return someSyncOperation(content);
146146
};
@@ -170,7 +170,7 @@ The loader context represents the properties that are available inside of a load
170170
Given the following example this require call is used:
171171
In `/abc/file.js`:
172172

173-
``` js
173+
``` javascript
174174
require('./loader1?xyz!loader2!./resource?rrr');
175175
```
176176

@@ -213,7 +213,7 @@ A function that can be called synchronously or asynchronously in order to return
213213

214214
<!-- eslint-skip -->
215215

216-
```js
216+
``` javascript
217217
this.callback(
218218
err: Error | null,
219219
content: string | Buffer,
@@ -261,13 +261,13 @@ An array of all the loaders. It is writeable in the pitch phase.
261261

262262
<!-- eslint-skip -->
263263

264-
```js
264+
``` javascript
265265
loaders = [{request: string, path: string, query: string, module: function}]
266266
```
267267

268268
In the example:
269269

270-
``` js
270+
``` javascript
271271
[
272272
{
273273
request: '/abc/loader1.js?xyz',
@@ -338,16 +338,33 @@ Should a source map be generated. Since generating source maps can be an expensi
338338
emitWarning(warning: Error)
339339
```
340340

341-
Emit a warning.
341+
Emit a warning that will be displayed in the output like the following:
342342

343+
``` bash
344+
WARNING in ./src/lib.js (./src/loader.js!./src/lib.js)
345+
Module Warning (from ./src/loader.js):
346+
Here is a Warning!
347+
@ ./src/index.js 1:0-25
348+
```
349+
350+
T> Note that the warnings will not be displayed if `stats.warnings` is set to `false`, or some other omit setting is used to `stats` such as `none` or `errors-only`. See the [stats configuration](/configuration/stats/#stats).
343351

344352
### `this.emitError`
345353

346354
``` typescript
347355
emitError(error: Error)
348356
```
349357

350-
Emit an error.
358+
Emit an error that also can be displayed in the output.
359+
360+
``` bash
361+
ERROR in ./src/lib.js (./src/loader.js!./src/lib.js)
362+
Module Error (from ./src/loader.js):
363+
Here is an Error!
364+
@ ./src/index.js 1:0-25
365+
```
366+
367+
T> Unlike throwing an Error directly, it will NOT interrupt the compilation process of the current module.
351368

352369

353370
### `this.loadModule`
@@ -471,3 +488,80 @@ Hacky access to the Compiler object of webpack.
471488
### `this._module`
472489
473490
Hacky access to the Module object being loaded.
491+
492+
493+
## Error Reporting
494+
495+
You can report errors from inside a loader by:
496+
497+
- Using [this.emitError](/api/loaders/#this-emiterror). Will report the errors without interrupting module's compilation.
498+
- Using `throw` (or other uncaught exception). Throwing an error while a loader is running will cause current module compilation failure.
499+
- Using `callback` (in async mode). Pass an error to the callback will also cause module compilation failure.
500+
501+
For example:
502+
503+
__./src/index.js__
504+
505+
``` javascript
506+
require('./loader!./lib');
507+
```
508+
509+
Throwing an error from loader:
510+
511+
__./src/loader.js__
512+
513+
``` javascript
514+
module.exports = function(source) {
515+
throw new Error('This is a Fatal Error!');
516+
};
517+
```
518+
519+
Or pass an error to the callback in async mode:
520+
521+
__./src/loader.js__
522+
523+
``` javascript
524+
module.exports = function(source) {
525+
const callback = this.async();
526+
//...
527+
callback(new Error('This is a Fatal Error!'), source);
528+
};
529+
```
530+
531+
The module will get bundled like this:
532+
533+
<!-- eslint-skip -->
534+
535+
``` javascript
536+
/***/ "./src/loader.js!./src/lib.js":
537+
/*!************************************!*\
538+
!*** ./src/loader.js!./src/lib.js ***!
539+
\************************************/
540+
/*! no static exports found */
541+
/***/ (function(module, exports) {
542+
543+
throw new Error("Module build failed (from ./src/loader.js):\nError: This is a Fatal Error!\n at Object.module.exports (/workspace/src/loader.js:3:9)");
544+
545+
/***/ })
546+
```
547+
548+
Then the build output will also display the error (Similar to `this.emitError`):
549+
550+
``` bash
551+
ERROR in ./src/lib.js (./src/loader.js!./src/lib.js)
552+
Module build failed (from ./src/loader.js):
553+
Error: This is a Fatal Error!
554+
at Object.module.exports (/workspace/src/loader.js:2:9)
555+
@ ./src/index.js 1:0-25
556+
```
557+
558+
As you can see below, not only error message, but also details about which loader and module are involved:
559+
560+
- the module path: `ERROR in ./src/lib.js`
561+
- the request string: `(./src/loader.js!./src/lib.js)`
562+
- the loader path: `(from ./src/loader.js)`
563+
- the caller path: `@ ./src/index.js 1:0-25`
564+
565+
W> The loader path in the error is displayed since webpack 4.12
566+
567+
T> All the errors and warnings will be recorded into `stats`. Please see [Stats Data](/api/stats/#errors-and-warnings).

0 commit comments

Comments
 (0)