Skip to content

Commit

Permalink
docs: add link
Browse files Browse the repository at this point in the history
  • Loading branch information
SyMind committed Mar 28, 2024
1 parent 63aee99 commit 422dc16
Show file tree
Hide file tree
Showing 2 changed files with 34 additions and 28 deletions.
24 changes: 12 additions & 12 deletions website/docs/en/api/node-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import { ApiMeta, Stability } from '../../../components/ApiMeta.tsx';

Rspack provides a Node.js API which can be used directly in Node.js runtime.

The Node.js API is useful in scenarios in which you need to customize the build or development process since all the reporting and error handling must be done manually and webpack only does the compiling part. For this reason the stats configuration options will not have any effect in the webpack() call.
The Node.js API is useful in scenarios in which you need to customize the build or development process since all the reporting and error handling must be done manually and webpack only does the compiling part. For this reason the [`stats`](/config/stats) configuration options will not have any effect in the `rspack()` call.

:::warning Compatible with Webpack Node.js API
`@rspack/core` is designed based on the Webpack Node.js API, with the goal of achieving the same functional behavior as Webpack.
Expand Down Expand Up @@ -43,23 +43,23 @@ rspack({}, (err, stats) => {
```

:::tip
The `err` object will not include compilation errors. Those must be handled separately using `stats.hasErrors()`, which will be covered in detail in the Error Handling section of this guide. The err object will only contain rspack-related issues, such as misconfiguration, etc.
The `err` object will not include compilation errors. Those must be handled separately using `stats.hasErrors()`, which will be covered in detail in the [Error Handling](/api/node-api#error-handling) section of this guide. The err object will only contain rspack-related issues, such as misconfiguration, etc.
:::

:::tip
You can provide the `rspack` function with an array of configurations. See the MultiCompiler section below for more information.
You can provide the `rspack` function with an array of configurations. See the [MultiCompiler](/api/node-api#multicompiler) section below for more information.
:::

## Compiler Instance

If you don’t pass the `rspack` runner function a callback, it will return a Rspack `Compiler` instance. This instance can be used to manually trigger the Rspack runner or have it build and watch for changes, much like the CLI. The `Compiler` instance provides the following methods:
If you don’t pass the `rspack` runner function a callback, it will return a Rspack `Compiler` instance. This instance can be used to manually trigger the Rspack runner or have it build and watch for changes, much like the [CLI](/api/cli). The `Compiler` instance provides the following methods:

- `.run(callback)`
- `.watch(watchOptions, handler)`

Typically, only one master `Compiler` instance is created, although child compilers can be created in order to delegate specific tasks. The `Compiler` is ultimately a function which performs bare minimum functionality to keep a lifecycle running. It delegates all the loading, bundling, and writing work to registered plugins.

The `hooks` property on a `Compiler` instance is used to register a plugin to any hook event in the `Compiler`'s lifecycle. The `RspackOptionsApply` utilities are used by Rspack to configure its `Compiler` instance with all the built-in plugins.
The `hooks` property on a `Compiler` instance is used to register a plugin to any hook event in the `Compiler`'s lifecycle. The [`RspackOptionsApply`](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack/src/rspackOptionsApply.ts) utilities are used by Rspack to configure its `Compiler` instance with all the built-in plugins.

The `run` method is then used to kickstart all compilation work. Upon completion, the given `callback` function is executed. The final logging of stats and errors should be done in this `callback` function.

Expand Down Expand Up @@ -93,7 +93,7 @@ Don't forget to close the compiler, so that low-priority work (like persistent c

## Watching

Calling the watch method triggers the rspack runner, but then watches for changes (much like CLI: rspack --watch), as soon as Rspack detects a change, runs again. Returns an instance of Watching.
Calling the watch method triggers the rspack runner, but then watches for changes (much like CLI: `rspack --watch`), as soon as Rspack detects a change, runs again. Returns an instance of Watching.

```js
watch(watchOptions, callback);
Expand All @@ -119,7 +119,7 @@ const watching = compiler.watch(
);
```

Watching options are covered in detail here.
`Watching` options are covered in detail [here](/config/watch#watchoptions).

:::warning
Filesystem inaccuracies may trigger multiple builds for a single change. In the example above, the `console.log` statement may fire multiple times for a single modification. Users should expect this behavior and may check `stats.hash` to see if the file hash has actually changed.
Expand Down Expand Up @@ -149,13 +149,13 @@ watching.invalidate();

## Stats Object

The `stats` object that is passed as a second argument of the `rspack()` callback, is a good source of information about the code compilation process. It includes:
The `stats` object that is passed as a second argument of the [`rspack()`](/api/node-api#rspack) callback, is a good source of information about the code compilation process. It includes:

- Errors and Warnings (if any)
- Timings
- Module and Chunk information

The Rspack CLI uses this information to display nicely formatted output in your console.
The [Rspack CLI](/api/cli) uses this information to display nicely formatted output in your console.

:::tip
When using the `MultiCompiler`, a `MultiStats` instance is returned that fulfills the same interface as `stats`, i.e. the methods described below.
Expand Down Expand Up @@ -186,11 +186,11 @@ stats.toJson({
});
```

All available options and presets are described in the stats documentation.
All available options and presets are described in the stats [documentation](/config/stats).

### stats.toString(options)

Returns a formatted string of the compilation information (similar to CLI output).
Returns a formatted string of the compilation information (similar to [CLI](/api/cli) output).

Options are the same as `stats.toJson(options)` with one addition:

Expand Down Expand Up @@ -291,7 +291,7 @@ rspack(

## Custom File Systems

By default, Rspack reads files and writes files to disk using a normal file system. However, it is possible to change the input or output behavior using a different kind of file system (memory, webDAV, etc). To accomplish this, one can change the `inputFileSystem` or `outputFileSystem`. For example, you can replace the default `outputFileSystem` with `memfs` to write files to memory instead of to disk:
By default, Rspack reads files and writes files to disk using a normal file system. However, it is possible to change the input or output behavior using a different kind of file system (memory, webDAV, etc). To accomplish this, one can change the `inputFileSystem` or `outputFileSystem`. For example, you can replace the default `outputFileSystem` with [`memfs`](https://github.com/streamich/memfs) to write files to memory instead of to disk:

```js
import { createFsFromVolume, Volume } from 'memfs';
Expand Down
38 changes: 22 additions & 16 deletions website/docs/zh/api/node-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import { ApiMeta, Stability } from '../../../components/ApiMeta.tsx';

Rspack 提供了 Node.js API,可以在 Node.js 运行时下直接使用。

当你需要自定义构建或开发流程时,Node.js API 非常有用,因为此时所有的报告和错误处理都必须自行实现,Rspack 仅仅负责编译的部分。所以 `stats` 配置选项不会在 `rspack()` 调用中生效。
当你需要自定义构建或开发流程时,Node.js API 非常有用,因为此时所有的报告和错误处理都必须自行实现,Rspack 仅仅负责编译的部分。所以 [`stats`](/config/stats) 配置选项不会在 `rspack()` 调用中生效。

:::warning 和 Webpack Node.js API 的兼容性
`@rspack/core` 是根据 Webpack Node.js API 设计的,旨在实现与 Webpack 相同的功能表现和行为。
Expand Down Expand Up @@ -43,25 +43,25 @@ rspack({}, (err, stats) => {
```

:::tip 提示
`err` 对象**不包含**编译错误,必须使用 `stats.hasErrors()` 单独处理,文档的错误处理将对这部分进行详细介绍`err` 对象只包含 Rspack 相关的问题,例如配置错误等。
`err` 对象**不包含**编译错误,必须使用 `stats.hasErrors()` 单独处理,文档的[错误处理](/api/node-api#错误处理)将对这部分进行详细介绍`err` 对象只包含 Rspack 相关的问题,例如配置错误等。
:::

:::tip 提示
你也可以为 rspack 函数提供一个配置数组。更多详细信息,请查看 MultiCompiler 章节。
你也可以为 rspack 函数提供一个配置数组。更多详细信息,请查看 [MultiCompiler](/api/node-api#multicompiler) 章节。
:::

## Compiler 实例

如果你不向 `rspack` 传入可执行的回调函数,它会返回一个 Rspack `Compiler` 实例。你可以通过手动执行它或者为它的构建时添加一个监听器,就像 CLI 类似。Compiler 实例提供了以下方法:
如果你不向 `rspack` 传入可执行的回调函数,它会返回一个 Rspack `Compiler` 实例。你可以通过手动执行它或者为它的构建时添加一个监听器,就像 [CLI](/api/cli) 类似。Compiler 实例提供了以下方法:

- `.run(callback)`
- `.watch(watchOptions, handler)`

通常情况下,仅会创建一个主要 `Compiler` 实例,虽然可以创建一些子 compiler 来代理到特定任务。`Compiler` 基本上只是执行最低限度的功能,以维持生命周期运行的功能。它将所有的加载、打包和写入工作,都委托到注册过的插件上。

`Compiler` 实例上的 `hooks` 属性,用于将一个插件注册到 `Compiler` 的生命周期中的所有钩子事件上。Rspack 使用 `RspackOptionsApply` 来配置 `Compiler` 实例以及所有内置插件。
`Compiler` 实例上的 `hooks` 属性,用于将一个插件注册到 `Compiler` 的生命周期中的所有钩子事件上。Rspack 使用 [`RspackOptionsApply`](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack/src/rspackOptionsApply.ts) 来配置 `Compiler` 实例以及所有内置插件。

使用 `run` 方法启动所有编译工作。完成之后,执行传入的的 callback 函数。最终记录下来的概括信息(stats)和错误(errors),都应在这个 callback 函数中获取。
使用 `run` 方法启动所有编译工作。完成之后,执行传入的的 `callback` 函数。最终记录下来的概括信息(stats)和错误(errors),都应在这个 callback 函数中获取。

:::warning 警告
这个 API 一次仅支持一个编译。当使用 `run` 或者 `watch` 时,调用 `close`,并等待它完成后再次执行 `run` 或者 `watch`。并发编译将破坏输出文件。
Expand All @@ -88,7 +88,7 @@ compiler.run((err, stats) => {
```

:::warning 警告
不要忘记关闭编译器,这样低优先级的工作(比如持久缓存)就有机会完成。
不要忘记关闭 compiler,这样低优先级的工作(比如持久缓存)就有机会完成。
:::

## 监听
Expand Down Expand Up @@ -119,7 +119,7 @@ const watching = compiler.watch(
);
```

`Watching` 配置选项的细节可以在这里查询
`Watching` 配置选项的细节可以在[这里](/config/watch#watchoptions)查询

:::warning 警告
文件系统不正确的问题,可能会对单次修改触发多次构建。因此,在上面的示例中,一次修改可能会多次触发 `console.log` 语句。用户应该预知此行为,并且可能需要检查 `stats.hash` 来查看文件哈希是否确实变更。
Expand All @@ -136,7 +136,7 @@ watching.close((closeErr) => {
```

:::warning 警告
不允许在监听器关闭或者失效前 再次监听或执行
不允许在监听器关闭或者失效前再次监听或执行
:::

## 无效化 `Watching`
Expand All @@ -149,13 +149,13 @@ watching.invalidate();

## Stats 对象

`stats` 对象会被作为 `rspack()` 回调函数的第二个参数传递,可以通过它获取到代码编译过程中的有用信息,包括:
`stats` 对象会被作为 [`rspack()`](/api/node-api#rspack) 回调函数的第二个参数传递,可以通过它获取到代码编译过程中的有用信息,包括:

- 错误和警告(如果有的话)
- 计时信息
- 模块和 chunk 信息

Rspack CLI 正是基于这些信息在控制台 展示友好的格式输出
[Rspack CLI](/api/cli) 正是基于这些信息在控制台展示友好的格式输出

:::tip 提示
当使用 `MultiCompiler` 时,会返回一个 `MultiStats` 实例,它实现与 `stats` 相同的接口,也就是下面描述的方法。
Expand All @@ -165,11 +165,11 @@ Rspack CLI 正是基于这些信息在控制台 展示友好的格式输出。

### stats.hasErrors()

可以用来检查编译期是否有错误, 返回值为 `true``false`
可以用来检查编译期是否有错误,返回值为 `true``false`

### stats.hasWarnings()

可以用来检查编译期是否有警告, 返回值为 `true``false`
可以用来检查编译期是否有警告,返回值为 `true``false`

### stats.toJson(options)

Expand All @@ -186,9 +186,11 @@ stats.toJson({
});
```

所有可用的配置选项和预设值都可查询 stats [文档](/config/stats)

### stats.toString(options)

以格式化的字符串形式返回描述编译信息(类似 CLI 的输出)。
以格式化的字符串形式返回描述编译信息(类似 [CLI](/api/cli) 的输出)。

配置对象与 `stats.toJson(options)` 一致,除了额外增加的一个选项:

Expand Down Expand Up @@ -242,6 +244,10 @@ rspack(
);
```

:::warning 警告
多个配置对象在执行时,不会并行执行。每个配置都只会在前一个处理结束后,才进行处理。
:::

## 错误处理

完备的错误处理中需要考虑以下三种类型的错误:
Expand Down Expand Up @@ -285,7 +291,7 @@ rspack(

## 自定义文件系统

默认情况下,Rspack 使用普通文件系统来读取文件并将文件写入磁盘。但是,还可以使用不同类型的文件系统(内存, webDAV 等)来更改输入或输出行为。为了实现这一点,可以改变 `inputFileSystem``outputFileSystem` 例如,可以使用 [`memfs`](https://github.com/streamich/memfs) 替换默认的 `outputFileSystem`,以将文件写入到内存中,而不是写入到磁盘:
默认情况下,Rspack 使用普通文件系统来读取文件并将文件写入磁盘。但是,还可以使用不同类型的文件系统(内存, webDAV 等)来更改输入或输出行为。为了实现这一点,可以改变 `inputFileSystem``outputFileSystem`例如,可以使用 [`memfs`](https://github.com/streamich/memfs) 替换默认的 `outputFileSystem`,以将文件写入到内存中,而不是写入到磁盘:

```js
import { createFsFromVolume, Volume } from 'memfs';
Expand All @@ -307,5 +313,5 @@ compiler.run((err, stats) => {
```

:::tip 提示
你指定的输出文件系统需要 兼容 Node 自身的 `fs` 模块接口, 接口需要提供 `mkdirp``join` 工具方法。
你指定的输出文件系统需要 兼容 Node 自身的 `fs` 模块接口,接口需要提供 `mkdirp``join` 工具方法。
:::

0 comments on commit 422dc16

Please sign in to comment.