Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: polish some documentations #9085

Merged
merged 3 commits into from
Jan 22, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion packages/rspack-tracing/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
# Tracing Utility for Rspack
# Tracing utility for Rspack

> Rspack's internal tracing tools, don't use it directly in your project, it may contain breaking change in minor & patch release right now.
2 changes: 1 addition & 1 deletion website/docs/en/api/cli.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ Options:
--configName Name of the configuration to use. [array]
```

## Common Flags
## Common flags

Here are some common flags that are supported by all Rspack commands:

Expand Down
7 changes: 5 additions & 2 deletions website/docs/en/blog/announcing-1-2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,16 @@ Notable changes:

- New features
- [Persistent cache](#persistent-cache): An experimental feature that improves hot start performance by up to **250%**.
- [Yarn pnp](#yarn-pnp)
- [Yarn PnP](#yarn-pnp)
- Performance improvements
- [Faster code splitting](#faster-code-splitting): An experimental flag that significantly improve the code splitting performance.
- [Watch scope change](#watch-scope-change)
- [Reduced memory usage](#reduced-memory-usage)
- [Smaller minification size](#smaller-minification-size)
- [Faster side effects optimization](#faster-side-effects-optimization)
- Ecosystem
- [Angular support](#angular-support)
- [Rsbuild v1.2](#rsbuild-v1-2)

## New features

Expand Down Expand Up @@ -61,7 +64,7 @@ If you encounter any issues while using persistent cache, please feel free to re

### Yarn PnP

Rspack has added support for [Yarn PnP](https://yarnpkg.com/features/pnp), which is enabled by default based on `process.versions.pnp` (that is, when the application is running in a Yarn pnp environment), and can also be forced to enable by configuring `resolve.pnp` to `true`.
Rspack has added support for [Yarn PnP](https://yarnpkg.com/features/pnp), which is enabled by default based on `process.versions.pnp` (that is, when the application is running in a Yarn PnP environment), and can also be forced to enable by configuring `resolve.pnp` to `true`.

```js title="rspack.config.js"
module.exports = {
Expand Down
2 changes: 1 addition & 1 deletion website/docs/zh/api/runtime-api/module-variables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ __dirname

`import.meta` 将特定上下文的元数据暴露给 JavaScript 模块,例如模块的 URL。它仅在 ESM(ECMAScript 模块)中可用。

> 请注意,Rspack 不支持直接访问 `import.meta`(将抛出警告)。因此,您应该访问其属性或使用解构赋值
> 请注意,Rspack 不支持直接访问 `import.meta`(将抛出警告)。因此,你应该访问其属性或使用解构赋值

<Columns>
```js title=源码
Expand Down
4 changes: 2 additions & 2 deletions website/docs/zh/blog/announcing-0-2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ sidebar: false

自 Rspack 0.1 版本发布的将近三个月以来,我们得到了非常多社区的关注和反馈,感谢大家对 Rspack 的支持。在 0.2 版本中,我们新增了诸多功能,如 realContentHash、DataURI、ESM format 的支持等,同时加强了与 webpack 的兼容性,并优化了诸多细节。

另外,得益于对 webpack API 良好的兼容性,我们对于周边生态也完成了进一步的兼容,例如,测试完成了对 vue-loader 17(对应 Vue3)和 15(对应 Vue2)版本的兼容,现在大家可以尝试在 Vue2 / 3 项目中使用 Rspack 了。我们期待您在 0.2 版本中体验到这些全新的改进,并欢迎您随时给我们提供反馈
另外,得益于对 webpack API 良好的兼容性,我们对于周边生态也完成了进一步的兼容,例如,测试完成了对 vue-loader 17(对应 Vue3)和 15(对应 Vue2)版本的兼容,现在大家可以尝试在 Vue2 / 3 项目中使用 Rspack 了。我们期待你在 0.2 版本中体验到这些全新的改进,并欢迎你随时给我们提供反馈

## 主要功能更新

Expand Down Expand Up @@ -79,7 +79,7 @@ module.exports = {
- `splitChunks.maxAsyncRequests`
- `splitChunks.maxInitialRequests`

在 0.2 版本中,我们会默认使用新的 `SplitChunksPlugin`。如果您遇到问题,请及时反馈,我们会尽快修复。您可以通过 `experiments.newSplitChunks: false` 来切换回旧版本的实现,但我们强烈建议您使用新版本。我们将在 0.3 版本中,移除掉旧有的实现。
在 0.2 版本中,我们会默认使用新的 `SplitChunksPlugin`。如果你遇到问题,请及时反馈,我们会尽快修复。你可以通过 `experiments.newSplitChunks: false` 来切换回旧版本的实现,但我们强烈建议你使用新版本。我们将在 0.3 版本中,移除掉旧有的实现。

### DataURI 支持

Expand Down
10 changes: 5 additions & 5 deletions website/docs/zh/blog/announcing-0-4.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Rspack 不再支持 Node.js 14,现在需要 Node.js 16+。

### 调整 @rspack/core 为 @rspack/cli 的 peer dependency

`@rspack/core` 现在是 `@rspack/cli` 的 peerDependency,而不是直接的依赖关系。这意味着现在您需要手动安装 `@rspack/core` 和 `@rspack/cli`。这使得 Rspack 更加接近 webpack。从长远来看,`@rspack/cli` 的定位将不再是开箱即用的解决方案。我们建议使用 [Rsbuild](https://rsbuild.dev/) 作为开箱即用的解决方案。
`@rspack/core` 现在是 `@rspack/cli` 的 peerDependency,而不是直接的依赖关系。这意味着现在你需要手动安装 `@rspack/core` 和 `@rspack/cli`。这使得 Rspack 更加接近 webpack。从长远来看,`@rspack/cli` 的定位将不再是开箱即用的解决方案。我们建议使用 [Rsbuild](https://rsbuild.dev/) 作为开箱即用的解决方案。

### 废弃默认转换

Expand Down Expand Up @@ -148,7 +148,7 @@ module.exports = {

### 废弃 builtin:sass-loader

`builtin:sass-loader` 现已被废弃。如果您正在使用它,请迁移到 `sass-loader`。Rspack 将在 v0.5.0 中移除 `builtin:sass-loader`。
`builtin:sass-loader` 现已被废弃。如果你正在使用它,请迁移到 `sass-loader`。Rspack 将在 v0.5.0 中移除 `builtin:sass-loader`。

### experiments.incrementalRebuild 配置废弃

Expand All @@ -158,7 +158,7 @@ module.exports = {

以前,一些 API 可能会通过从 @rspack/core 重新导出而被意外导出。现在通过此重构,我们从 @rspack/core 中清理了导出的 API。

这不应该造成任何问题,但如果您意外导出了 API,则可能会出现问题,您可能会以不正确的方式使用 Rspack。
这不应该造成任何问题,但如果你意外导出了 API,则可能会出现问题,你可能会以不正确的方式使用 Rspack。

如果确实有需要从此重构中移除的 API,请在 Rspack 仓库中提出问题。

Expand All @@ -182,7 +182,7 @@ module.exports = {

### 选择 `@rspack/cli` 还是 `Rsbuild`?

如果您的应用程序是 CSR 应用程序,则我们强烈建议您使用 Rsbuild 而不是自行配置 Rspack,因为与 `@rspack/cli` 相比,Rsbuild 更容易使用。
如果你的应用程序是 CSR 应用程序,则我们强烈建议你使用 Rsbuild 而不是自行配置 Rspack,因为与 `@rspack/cli` 相比,Rsbuild 更容易使用。

### 升级 Node.js 版本

Expand Down Expand Up @@ -217,7 +217,7 @@ module.exports = {

### 对于 React 应用程序,请使用 `@rspack/plugin-react-refresh` 来支持 Fast Refresh

当我们禁用默认转换时,`builtin.react.refresh` 将无法工作,因此您需要使用 `@rspack/plugin-react-refresh` 来启用 Fast Refresh,更多细节请参阅 [Deprecating builtin.react.refresh](#废弃-builtinreactrefresh)。
当我们禁用默认转换时,`builtin.react.refresh` 将无法工作,因此你需要使用 `@rspack/plugin-react-refresh` 来启用 Fast Refresh,更多细节请参阅 [Deprecating builtin.react.refresh](#废弃-builtinreactrefresh)。

### 迁移 builtin options 到 builtin plugins

Expand Down
28 changes: 14 additions & 14 deletions website/docs/zh/blog/announcing-0-5.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ import { PackageManagerTabs } from '@theme';

### 支持 rspack.HotModuleReplacementPlugin

支持 `rspack.HotModuleReplacementPlugin`,如果您没有使用 `@rspack/dev-server` 而是使用自定义的开发服务器,则需要使用 `HotModuleReplacementPlugin` 来启用 HMR,而不再将 `devServer.hot` 设置为 `true`,这与 webpack 相同。这提供了更多在内部使用 `HotModuleReplacementPlugin` 的插件的兼容性。
支持 `rspack.HotModuleReplacementPlugin`,如果你没有使用 `@rspack/dev-server` 而是使用自定义的开发服务器,则需要使用 `HotModuleReplacementPlugin` 来启用 HMR,而不再将 `devServer.hot` 设置为 `true`,这与 webpack 相同。这提供了更多在内部使用 `HotModuleReplacementPlugin` 的插件的兼容性。

### 移除默认转换

Expand All @@ -33,7 +33,7 @@ import { PackageManagerTabs } from '@theme';
- `"tsx"`
- `"jsx"`

为了实现旧有的行为,请删除 `rule.type` 或将其更改为 `"javascript/auto"` 并应用您的自定义加载器配置
为了实现旧有的行为,请删除 `rule.type` 或将其更改为 `"javascript/auto"` 并应用你的自定义加载器配置

转译 `.jsx` 文件:

Expand Down Expand Up @@ -150,9 +150,9 @@ module.exports = {

### 将 @swc/helpers 和 react-refresh 调整为 peerDependencies

在我们移除默认转换之前,可以通过 `target` 将您的代码降级为 es5,并通过 `builtin.react.refresh` 将 react 刷新助手代码插入到您的 react 组件中,因此我们安装了 `@swc/helpers` 和 `react-refresh` 作为 `@rspack/core` 的依赖项,以提供开箱即用的体验。但是现在我们已经移除了默认转换,并建议使用 Rsbuild 来获得开箱即用的体验,因此 `@swc/helpers` 和 `react-refresh` 不再需要由 `@rspack/core` 安装,我们将它们调整为 `@rspack/core` 的 peerDependencies。
在我们移除默认转换之前,可以通过 `target` 将你的代码降级为 es5,并通过 `builtin.react.refresh` 将 react 刷新助手代码插入到你的 react 组件中,因此我们安装了 `@swc/helpers` 和 `react-refresh` 作为 `@rspack/core` 的依赖项,以提供开箱即用的体验。但是现在我们已经移除了默认转换,并建议使用 Rsbuild 来获得开箱即用的体验,因此 `@swc/helpers` 和 `react-refresh` 不再需要由 `@rspack/core` 安装,我们将它们调整为 `@rspack/core` 的 peerDependencies。

如果您正在使用 `builtin:swc-loader` 或 `swc-loader` 的 `externalHelpers: true` 功能,现在您需要将 `@swc/helpers` 安装为项目的 dependencies。如果您正在使用 `@rspack/plugin-react-refresh`,现在您需要将 `react-refresh` 安装为项目的 devDependencies。
如果你正在使用 `builtin:swc-loader` 或 `swc-loader` 的 `externalHelpers: true` 功能,现在你需要将 `@swc/helpers` 安装为项目的 dependencies。如果你正在使用 `@rspack/plugin-react-refresh`,现在你需要将 `react-refresh` 安装为项目的 devDependencies。

### 移除已弃用的 builtins options

Expand Down Expand Up @@ -188,11 +188,11 @@ module.exports = {

## 迁移指南

v0.5.0 移除了许多已经弃用的功能,除此之外,v0.5.0 引入了四个破坏性更新,如果您正在使用 Rspack 开发应用,那么您只需要关注其中两个。因此,如果您已经迁移到 v0.4+ 并且没有弃用警告,那么 v0.5.0 将很容易迁移,如果您还没有,请查看 [v0.4.0 迁移指南](https://www.rspack.dev/blog/announcing-0.4#migration-guide).
v0.5.0 移除了许多已经弃用的功能,除此之外,v0.5.0 引入了四个破坏性更新,如果你正在使用 Rspack 开发应用,那么你只需要关注其中两个。因此,如果你已经迁移到 v0.4+ 并且没有弃用警告,那么 v0.5.0 将很容易迁移,如果你还没有,请查看 [v0.4.0 迁移指南](https://www.rspack.dev/blog/announcing-0.4#migration-guide).

### 添加 resolve.extensions

这是一个很可能会影响到您的破坏性更新
这是一个很可能会影响到你的破坏性更新

在将 `@rspack/core` 升级到 v0.5.0 后,如果构建失败并出现错误:`Can't resolve './src/foo.tsx'`,或者 `Can't resolve './src/foo.ts'`,或者 `Can't resolve './src/foo.jsx'`,则需要在配置中添加 `resolve.extensions = ['...', '.tsx', '.ts', '.jsx']`。

Expand All @@ -205,27 +205,27 @@ const configuration = {
}
```

你只需要将所需的扩展名添加到 `resolve.extensions` 中。例如,如果您没有使用任何 `.tsx` 或 `.ts` 文件,只使用 `.js` 或 `.jsx` 文件,则只需要添加 `'.jsx'` 到 `resolve.extensions` 中。`'.js'` 是默认扩展名之一,所有默认扩展名(`['.js', '.json', '.wasm']`)都由 `'...'` 表示。
你只需要将所需的扩展名添加到 `resolve.extensions` 中。例如,如果你没有使用任何 `.tsx` 或 `.ts` 文件,只使用 `.js` 或 `.jsx` 文件,则只需要添加 `'.jsx'` 到 `resolve.extensions` 中。`'.js'` 是默认扩展名之一,所有默认扩展名(`['.js', '.json', '.wasm']`)都由 `'...'` 表示。

### 安装 @swc/helpers 或 react-refresh

这是一个很可能会影响到您的破坏性更新
这是一个很可能会影响到你的破坏性更新

在将 `@rspack/core` 升级到 v0.5.0 后,如果构建失败并出现错误:`Failed to resolve @swc/helpers/some-helper` 或 `Failed to resolve react-refresh/some-module`,则需要在您的项目中安装 `@swc/helpers` 或 `react-refresh`。
在将 `@rspack/core` 升级到 v0.5.0 后,如果构建失败并出现错误:`Failed to resolve @swc/helpers/some-helper` 或 `Failed to resolve react-refresh/some-module`,则需要在你的项目中安装 `@swc/helpers` 或 `react-refresh`。

如果您正在使用 `builtin:swc-loader` 或 `swc-loader` 的 `externalHelpers: true` 功能,现在您需要将 `@swc/helpers` 安装为项目的 dependencies。
如果你正在使用 `builtin:swc-loader` 或 `swc-loader` 的 `externalHelpers: true` 功能,现在你需要将 `@swc/helpers` 安装为项目的 dependencies。

<PackageManagerTabs command="install @swc/helpers" />

如果您正在使用 `@rspack/plugin-react-refresh`,现在您需要将 `react-refresh` 安装为项目的 devDependencies。
如果你正在使用 `@rspack/plugin-react-refresh`,现在你需要将 `react-refresh` 安装为项目的 devDependencies。

<PackageManagerTabs command="install react-refresh" />

### 调用 rspack.HotModuleReplacementPlugin

如果您正在使用 `@rspack/cli`、Rsbuild 或其他 Rspack 的上层框架来开发应用程序,您不需要担心这个问题。这应该由上层框架或 cli 处理好。但是,如果您正在使用 `@rspack/core` 与自定义开发服务器(不是 `@rspack/dev-server` 或 `webpack-dev-server`),或者正在开发自定义开发服务器,则需要注意这一点。
如果你正在使用 `@rspack/cli`、Rsbuild 或其他 Rspack 的上层框架来开发应用程序,你不需要担心这个问题。这应该由上层框架或 cli 处理好。但是,如果你正在使用 `@rspack/core` 与自定义开发服务器(不是 `@rspack/dev-server` 或 `webpack-dev-server`),或者正在开发自定义开发服务器,则需要注意这一点。

之前,在 Rspack 中启用 HMR 需要将 `devServer.hot` 设置为 `true`,但现在您需要在自定义开发服务器中自己调用 `HotModuleReplacementPlugin`。
之前,在 Rspack 中启用 HMR 需要将 `devServer.hot` 设置为 `true`,但现在你需要在自定义开发服务器中自己调用 `HotModuleReplacementPlugin`。

```diff
class CustomDevServer {
Expand All @@ -240,7 +240,7 @@ class CustomDevServer {

### 不要在 rspack(options) 调用之后修改入口配置

如果您正在使用 `@rspack/cli`、Rsbuild 或其他 Rspack 的上层框架来开发应用程序,您不需要担心这个问题。这应该由上层框架或 cli 处理好。但是如果您正在开发 Rspack 插件或上层框架,您需要注意这一点
如果你正在使用 `@rspack/cli`、Rsbuild 或其他 Rspack 的上层框架来开发应用程序,你不需要担心这个问题。这应该由上层框架或 cli 处理好。但是如果你正在开发 Rspack 插件或上层框架,你需要注意这一点

之前,在 Rspack 中添加额外的入口,需要将其添加到 `compiler.options.entry` 中,但现在需要调用 `EntryPlugin`。

Expand Down
3 changes: 3 additions & 0 deletions website/docs/zh/blog/announcing-1-2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@ Rspack v1.2 已经正式发布!
- [减少内存使用](#减少内存使用)
- [更小的压缩体积](#更小的压缩体积)
- [更快的副作用优化](#更快的副作用优化)
- 生态系统
- [Angular 支持](#angular-支持)
- [Rsbuild v1.2](#rsbuild-v1-2)

## 新功能

Expand Down
6 changes: 3 additions & 3 deletions website/docs/zh/blog/module-federation-added-to-rspack.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,11 @@ v1.5 可通过 [@module-federation/enhanced](https://www.npmjs.com/package/@modu

Rspack 中的模块联邦为加速打包工具的代码共享提供了多种创意的迁移方式。webpack 和 Rspack 都可以共享代码,依赖于模块联邦在 v1.5 中引入的相同的集中式运行时。这确保了维护功能平衡的可管理性,并且不需要额外 fork 模块联邦来自定义它。

**渐进式迁移**到 Rspack 可以通过模块联邦来实现。如果您有锁定在 webpack 的插件或无法完全切换到 Rspack,通过模块联邦,您可以允许 Rspack 和 webpack 共享依赖和代码,这意味着更多的代码可以通过 Rspack 构建,而使用 webpack 的 Host 则做更少的工作,但仍然获得相同的结果。[示例:webpack 和 Rspack 交互](https://github.com/module-federation/module-federation-examples/pull/3490)
**渐进式迁移**到 Rspack 可以通过模块联邦来实现。如果你有锁定在 webpack 的插件或无法完全切换到 Rspack,通过模块联邦,你可以允许 Rspack 和 webpack 共享依赖和代码,这意味着更多的代码可以通过 Rspack 构建,而使用 webpack 的 Host 则做更少的工作,但仍然获得相同的结果。[示例:webpack 和 Rspack 交互](https://github.com/module-federation/module-federation-examples/pull/3490)

**通过模块联邦共享 node_modules 加速构建速度**。可以告诉 webpack 将共享依赖设置为 `import: false`,然后 Rspack 可以编译所有共享模块,减少解析开销和 webpack 构建部分需要执行的代码量,通过将其委托给 Rspack,使共享模块的编译只需要几毫秒即可完成。[示例:将 Rspack 打包的 Vendor 提供给 webpack 应用](https://github.com/module-federation/module-federation-examples/pull/3491)

**一次性进行迁移**。由于 webpack 模块联邦([@module-federation/enhanced](https://www.npmjs.com/package/@module-federation/enhanced))和 Rspack 模块联邦之间的接口是一致的,因此用户可以切换到任何现有的模块联邦的构建到 Rspack。我们建议使用 `@module-federation/enhanced` 来构建遗留的 webpack 应用,该插件利用我们的新设计并导出的 ModuleFederationPlugin。但是,您仍然可以使用 webpack 中提供的原始的模块联邦插件。Rspack 能够与现有的模块联邦应用进行无缝衔接。
**一次性进行迁移**。由于 webpack 模块联邦([@module-federation/enhanced](https://www.npmjs.com/package/@module-federation/enhanced))和 Rspack 模块联邦之间的接口是一致的,因此用户可以切换到任何现有的模块联邦的构建到 Rspack。我们建议使用 `@module-federation/enhanced` 来构建遗留的 webpack 应用,该插件利用我们的新设计并导出的 ModuleFederationPlugin。但是,你仍然可以使用 webpack 中提供的原始的模块联邦插件。Rspack 能够与现有的模块联邦应用进行无缝衔接。

## 与 webpack 模块联邦的性能比较

Expand Down Expand Up @@ -104,7 +104,7 @@ new ModuleFederationPlugin({
})
```

模块联邦也可以以动态的方式使用,不需要任何构建时插件。您可以在此处阅读[更多有关 v1.5 运行时的信息](https://github.com/module-federation/universe/tree/feat/async-boundary-option/packages/runtime)。
模块联邦也可以以动态的方式使用,不需要任何构建时插件。你可以在此处阅读[更多有关 v1.5 运行时的信息](https://github.com/module-federation/universe/tree/feat/async-boundary-option/packages/runtime)。

```js
// 可以使用运行时 SDK 加载模块,而无需依赖构建插件。
Expand Down
Loading
Loading