Skip to content

Commit 87ff236

Browse files
h-a-n-achenjiahan
h-a-n-a
and
chenjiahan
authored
docs(diagnostic): add loader experimental diagnostic API (#10287)
* docs(diagnostic): add loader experimental diagnostic API * Update website/docs/en/api/loader-api/context.mdx Co-authored-by: neverland <[email protected]> * Update website/docs/zh/api/loader-api/context.mdx Co-authored-by: neverland <[email protected]> * Update website/docs/zh/api/loader-api/context.mdx Co-authored-by: neverland <[email protected]> * Update website/docs/en/api/loader-api/context.mdx Co-authored-by: neverland <[email protected]> * Update website/docs/en/api/loader-api/context.mdx Co-authored-by: neverland <[email protected]> * Update website/docs/zh/api/loader-api/context.mdx Co-authored-by: neverland <[email protected]> * docs: update --------- Co-authored-by: neverland <[email protected]>
1 parent 45bf974 commit 87ff236

File tree

2 files changed

+215
-1
lines changed

2 files changed

+215
-1
lines changed

‎website/docs/en/api/loader-api/context.mdx‎

Lines changed: 110 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { ApiMeta, Stability } from '@components/ApiMeta';
12
import WebpackLicense from '@components/WebpackLicense';
23

34
<WebpackLicense from="https://webpack.js.org/api/loaders/#the-loader-context" />
@@ -180,7 +181,11 @@ Alias of [this.addDependency()](#thisadddependency).
180181
function emitError(error: Error): void;
181182
```
182183

183-
Emit an error. Unlike `throw` and `this.callback(err)` in the loader, it does not mark the current module as a compilation failure, it just adds an error to Rspack's Compilation and displays it on the command line at the end of this compilation.
184+
Emit an error.
185+
186+
::: info
187+
Unlike `throw` and `this.callback(err)` in the loader, it does not mark the current module as a compilation failure, it just adds an error to Rspack's Compilation and displays it on the command line at the end of this compilation.
188+
:::
184189

185190
## this.emitWarning()
186191

@@ -192,6 +197,110 @@ function emitWarning(warning: Error): void;
192197

193198
Emit a warning.
194199

200+
## this.experiments.emitDiagnostic()
201+
202+
<ApiMeta stability={Stability.Experimental} />
203+
204+
- **Type:**
205+
206+
```ts
207+
interface DiagnosticLocation {
208+
/** Text for highlighting the location */
209+
text?: string;
210+
/** 1-based line */
211+
line: number;
212+
/** 0-based column in bytes */
213+
column: number;
214+
/** Length in bytes */
215+
length: number;
216+
}
217+
218+
interface Diagnostic {
219+
message: string;
220+
help?: string;
221+
sourceCode?: string;
222+
/**
223+
* Location to the source code.
224+
*
225+
* If `sourceCode` is not provided, location will be omitted.
226+
*/
227+
location?: DiagnosticLocation;
228+
file?: string;
229+
severity: 'error' | 'warning';
230+
}
231+
232+
function emitDiagnostic(diagnostic: Diagnostic): void;
233+
```
234+
235+
Formats and emits a diagnostic message (error or warning log). Supports the display of module paths, source code snippets and line/column numbers.
236+
237+
::: info
238+
Unlike `throw` and `this.callback(err)` in the loader, it does not mark the current module as a compilation failure, it just adds an error to Rspack's Compilation and displays it on the command line at the end of this compilation.
239+
:::
240+
241+
- Basic example:
242+
243+
When only `message` and `severity` are provided, only the basic module error information will be printed.
244+
245+
```js title="loader.js"
246+
/** @type {import("@rspack/core").LoaderDefinition} */
247+
module.exports = function () {
248+
this.experiments.emitDiagnostic({
249+
message: '`React` is not defined',
250+
severity: 'error',
251+
});
252+
this.experiments.emitDiagnostic({
253+
message: '`React` is not defined',
254+
severity: 'warning',
255+
});
256+
return '';
257+
};
258+
```
259+
260+
This will print:
261+
262+
```
263+
ERROR in (./loader.js!)
264+
× ModuleError: `React` is not defined
265+
266+
WARNING in (./loader.js!)
267+
⚠ ModuleWarning: `React` is not defined
268+
```
269+
270+
- Printing code snippet:
271+
272+
```js title="loader.js"
273+
/** @type {import("@rspack/core").LoaderDefinition} */
274+
module.exports = function () {
275+
this.experiments.emitDiagnostic({
276+
message: '`React` is not defined',
277+
severity: 'error',
278+
sourceCode: `<div></div>`,
279+
location: {
280+
line: 1,
281+
column: 1,
282+
length: 3,
283+
},
284+
file: './some-file.js',
285+
});
286+
return '';
287+
};
288+
```
289+
290+
This will print:
291+
292+
```
293+
ERROR in ./some-file.js
294+
./file.js 1:1-4
295+
× ModuleError: `React` is not defined
296+
╭────
297+
1 │ <div></div>
298+
· ───
299+
╰────
300+
```
301+
302+
Here, `./some-file.js` is the value passed to the `file` field.
303+
195304
## this.emitFile()
196305

197306
- **Type:**

‎website/docs/zh/api/loader-api/context.mdx‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { ApiMeta, Stability } from '@components/ApiMeta';
12
import WebpackLicense from '@components/WebpackLicense';
23

34
<WebpackLicense from="https://webpack.docschina.org/api/loaders/#the-loader-context" />
@@ -187,6 +188,110 @@ function emitWarning(warning: Error): void;
187188

188189
发出一个警告。
189190

191+
## this.experiments.emitDiagnostic()
192+
193+
<ApiMeta stability={Stability.Experimental} />
194+
195+
- **类型：**
196+
197+
```ts
198+
interface DiagnosticLocation {
199+
/** Text for highlighting the location */
200+
text?: string;
201+
/** 1-based line */
202+
line: number;
203+
/** 0-based column in bytes */
204+
column: number;
205+
/** Length in bytes */
206+
length: number;
207+
}
208+
209+
interface Diagnostic {
210+
message: string;
211+
help?: string;
212+
sourceCode?: string;
213+
/**
214+
* Location to the source code.
215+
*
216+
* If `sourceCode` is not provided, location will be omitted.
217+
*/
218+
location?: DiagnosticLocation;
219+
file?: string;
220+
severity: 'error' | 'warning';
221+
}
222+
223+
function emitDiagnostic(diagnostic: Diagnostic): void;
224+
```
225+
226+
格式化并输出一个诊断信息（错误或警告日志），支持显示模块路径、源代码片段和行列号。
227+
228+
::: info
229+
与在 loader 中 `throw` 和 `this.callback(err)` 不同，它不会标记当前模块为编译失败，只会在 Rspack 的 Compilation 上添加一个错误，并在此次编译结束后显示在命令行中。
230+
:::
231+
232+
- 基础示例：
233+
234+
当仅使用 `message` 和 `severity` 时，仅会打印基础的模块错误信息。
235+
236+
```js title="loader.js"
237+
/** @type {import("@rspack/core").LoaderDefinition} */
238+
module.exports = function () {
239+
this.experiments.emitDiagnostic({
240+
message: '`React` is not defined',
241+
severity: 'error',
242+
});
243+
this.experiments.emitDiagnostic({
244+
message: '`React` is not defined',
245+
severity: 'warning',
246+
});
247+
return '';
248+
};
249+
```
250+
251+
将会打印：
252+
253+
```
254+
ERROR in (./loader.js!)
255+
× ModuleError: `React` is not defined
256+
257+
WARNING in (./loader.js!)
258+
⚠ ModuleWarning: `React` is not defined
259+
```
260+
261+
- 打印代码片段：
262+
263+
```js title="loader.js"
264+
/** @type {import("@rspack/core").LoaderDefinition} */
265+
module.exports = function () {
266+
this.experiments.emitDiagnostic({
267+
message: '`React` is not defined',
268+
severity: 'error',
269+
sourceCode: `<div></div>`,
270+
location: {
271+
line: 1,
272+
column: 1,
273+
length: 3,
274+
},
275+
file: './some-file.js',
276+
});
277+
return '';
278+
};
279+
```
280+
281+
将会打印：
282+
283+
```
284+
ERROR in ./some-file.js
285+
./file.js 1:1-4
286+
× ModuleError: `React` is not defined
287+
╭────
288+
1 │ <div></div>
289+
· ───
290+
╰────
291+
```
292+
293+
其中 `./some-file.js` 为传入的 `file` 字段。
294+
190295
## this.emitFile()
191296

192297
- **类型：**

0 commit comments

Comments
 (0)