@modern-js/main-doc 2.45.0 → 2.46.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/en/components/stream-ssr-performance.mdx +0 -0
- package/docs/en/guides/advanced-features/rspack-start.mdx +62 -14
- package/docs/en/guides/advanced-features/ssr/stream.mdx +12 -0
- package/docs/en/guides/basic-features/html.mdx +0 -2
- package/docs/en/guides/get-started/glossary.mdx +6 -0
- package/docs/zh/components/stream-ssr-performance.mdx +0 -0
- package/docs/zh/guides/advanced-features/rspack-start.mdx +62 -15
- package/docs/zh/guides/advanced-features/ssr/stream.mdx +12 -0
- package/docs/zh/guides/basic-features/css-modules.mdx +1 -1
- package/docs/zh/guides/basic-features/html.mdx +0 -2
- package/docs/zh/guides/get-started/glossary.mdx +6 -0
- package/docs/zh/guides/topic-detail/generator/plugin/api/onForged.md +1 -1
- package/package.json +7 -7
- package/docs/en/configure/app/tools/inspector.mdx +0 -9
- package/docs/zh/configure/app/tools/inspector.mdx +0 -9
|
File without changes
|
|
@@ -25,27 +25,18 @@ After the project is created, you can experience the project by running `pnpm ru
|
|
|
25
25
|
:::tip
|
|
26
26
|
When using Rspack as the bundler, the following Features are temporarily unavailable as some of the capabilities are still under development and we will provide support in the future.
|
|
27
27
|
|
|
28
|
-
- Storybook Devtool
|
|
29
28
|
- The usage of [useLoader](/guides/basic-features/data/data-fetch.html) in Client Side Rendering
|
|
30
29
|
|
|
31
30
|
:::
|
|
32
31
|
|
|
33
32
|
## Enable Rspack build
|
|
34
33
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
```bash
|
|
38
|
-
$ pnpm run new
|
|
39
|
-
? Please select the operation you want: Enable features
|
|
40
|
-
? Please select the feature name: Enable Rspack Build
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
After executing the command, enable the Rspack build in `modern.config.ts`:
|
|
34
|
+
Since Modern.js MAJOR_VERSION.46.0, you can enable Rspack build by add the following configuration in `modern.config.ts`:
|
|
44
35
|
|
|
45
36
|
```diff title=modern.config.ts
|
|
46
37
|
import { appTools, defineConfig } from '@modern-js/app-tools';
|
|
47
38
|
|
|
48
|
-
|
|
39
|
+
export default defineConfig({
|
|
49
40
|
plugins: [
|
|
50
41
|
appTools({
|
|
51
42
|
+ bundler: 'experimental-rspack',
|
|
@@ -54,6 +45,10 @@ import { appTools, defineConfig } from '@modern-js/app-tools';
|
|
|
54
45
|
});
|
|
55
46
|
```
|
|
56
47
|
|
|
48
|
+
:::tip
|
|
49
|
+
If your current version is lower than MAJOR_VERSION.46.0, you can upgrade by executing `npx modern upgrade`.
|
|
50
|
+
:::
|
|
51
|
+
|
|
57
52
|
import RspackPrecautions from '@modern-js/builder-doc/docs/en/shared/rspackPrecautions.md';
|
|
58
53
|
|
|
59
54
|
<RspackPrecautions />
|
|
@@ -62,15 +57,69 @@ import RspackPrecautions from '@modern-js/builder-doc/docs/en/shared/rspackPreca
|
|
|
62
57
|
|
|
63
58
|
After enabling Rspack building capability, further configuration migration is needed by referring to the [Configuration Differences](https://modernjs.dev/builder/en/guide/advanced/rspack-start.html#migrating-from-webpack-to-rspack).
|
|
64
59
|
|
|
60
|
+
In Modern.js, the [tools.webpack](/configure/app/tools/webpack) and [tools.webpackChain](/configure/app/tools/webpack-chain) configurations only take effect in webpack mode, after turning on the Rspack build, you can modify it to [tools.rspack](/configure/app/tools/rspack) and [tools.bundlerChain](/configure/app/tools/bundler-chain).
|
|
61
|
+
|
|
62
|
+
```diff
|
|
63
|
+
export default {
|
|
64
|
+
tools: {
|
|
65
|
+
- webppack: (config, { env }) => {
|
|
66
|
+
+ rspack: (config, { env }) => {
|
|
67
|
+
if (env === 'development') {
|
|
68
|
+
config.devtool = 'cheap-module-eval-source-map';
|
|
69
|
+
}
|
|
70
|
+
return config;
|
|
71
|
+
},
|
|
72
|
+
- webpackChain: (chain, { env }) => {
|
|
73
|
+
+ bundlerChain: (chain, { env }) => {
|
|
74
|
+
if (env === 'development') {
|
|
75
|
+
chain.devtool('cheap-module-eval-source-map');
|
|
76
|
+
}
|
|
77
|
+
},
|
|
78
|
+
},
|
|
79
|
+
};
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
:::tip
|
|
83
|
+
After turning on the Rspack build capability, there are currently a small number of configurations that are not supported in Rspack, such as [source.moduleScopes](/configure/app/source/module-scopes), [security.sri](/configure/app/security/sri) etc.
|
|
84
|
+
|
|
85
|
+
For unsupported configurations, we have marked `Bundler: only support webpack` or `Bundler: only support Rspack` in the document. Please refer to the specific configuration introduction.
|
|
86
|
+
:::
|
|
87
|
+
|
|
88
|
+
## Modify transpile configuration
|
|
89
|
+
|
|
90
|
+
Modern.js uses Rspack [builtin:swc-loader](https://www.rspack.dev/guide/builtin-swc-loader.html) for code translation in Rspack mode.
|
|
91
|
+
|
|
92
|
+
Modern.js has provided a more convenient configuration for the common configuration of `builtin:swc-loader`, such as: configuring the component library to import it on demand through [source.transformImport](/configure/app/source/transform-import). If you have custom configuration requirements for `builtin:swc-loader`, you can refer to the following code:
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
export default {
|
|
96
|
+
tools: {
|
|
97
|
+
bundlerChain: (chain, { CHAIN_ID }) => {
|
|
98
|
+
chain.module
|
|
99
|
+
.rule(CHAIN_ID.RULE.JS)
|
|
100
|
+
.use(CHAIN_ID.USE.SWC)
|
|
101
|
+
.tap(options => {
|
|
102
|
+
options.xxx = '';
|
|
103
|
+
return options;
|
|
104
|
+
});
|
|
105
|
+
},
|
|
106
|
+
}
|
|
107
|
+
};
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
:::tip
|
|
111
|
+
When Rspack build is enabled, `babel-loader` is not enabled by default. If you need to add some babel plugins, you can configure it through [tools.babel](/configure/app/tools/babel). This will generate additional compilation overhead and slow down the Rspack build speed to a certain extent.
|
|
112
|
+
:::
|
|
113
|
+
|
|
65
114
|
## The relationship between Rspack and Modern.js versions
|
|
66
115
|
|
|
67
116
|
Usually, the latest version of Rspack will be integrated into Modern.js. You can update the Modern.js-related dependencies and built-in Rspack to the latest version by using `npx modern upgrade` in your project.
|
|
68
117
|
|
|
69
118
|
However, Modern.js uses a locked version dependency method (non-automatic upgrade) for Rspack. Due to differences in release cycles, the version of Rspack integrated into Modern.js may be behind the latest version of Rspack.
|
|
70
119
|
|
|
71
|
-
When Rspack is enabled for building through dev / build, the current version of Rspack used in the framework will be printed automatically:
|
|
120
|
+
When Rspack is enabled for building through dev / build, the current version of Rspack used in the framework will be printed automatically when [debugging mode](https://rsbuild.dev/guide/debug/debug-mode) is turned on:
|
|
72
121
|
|
|
73
|
-
|
|
74
123
|
|
|
75
124
|
### Override the Built-in Rspack Version
|
|
76
125
|
|
|
@@ -84,7 +133,6 @@ For example, if you are using pnpm, you can update the Rspack version with `over
|
|
|
84
133
|
"overrides": {
|
|
85
134
|
"@rspack/core": "nightly",
|
|
86
135
|
"@rspack/plugin-react-refresh": "nightly",
|
|
87
|
-
"@rspack/plugin-html": "nightly"
|
|
88
136
|
}
|
|
89
137
|
}
|
|
90
138
|
}
|
|
@@ -228,9 +228,21 @@ function ErrorElement() {
|
|
|
228
228
|
}
|
|
229
229
|
```
|
|
230
230
|
|
|
231
|
+
## Waiting for all content to load for spiders
|
|
232
|
+
|
|
233
|
+
Streaming offers a better user experience because the user can see the content as it becomes available.
|
|
234
|
+
|
|
235
|
+
However, when a spider visits your page, you might want to let all of the content load first and then produce the final HTML output instead of revealing it progressively.
|
|
236
|
+
|
|
237
|
+
Modern.js uses [isbot](https://www.npmjs.com/package/isbot) to examine the user-agent of requests, determining whether they come from a crawler.
|
|
238
|
+
|
|
231
239
|
:::info More
|
|
232
240
|
|
|
233
241
|
1. [Deferred Data](https://reactrouter.com/en/main/guides/deferred)
|
|
234
242
|
2. [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37)
|
|
235
243
|
|
|
236
244
|
:::
|
|
245
|
+
|
|
246
|
+
import StreamSSRPerformance from '@site-docs/components/stream-ssr-performance';
|
|
247
|
+
|
|
248
|
+
<StreamSSRPerformance />
|
|
@@ -46,6 +46,12 @@ import ModuleFederation from '@modern-js/builder-doc/docs/en/shared/module-feder
|
|
|
46
46
|
|
|
47
47
|
<ModuleFederation />
|
|
48
48
|
|
|
49
|
+
## Rsbuild
|
|
50
|
+
|
|
51
|
+
import Rsbuild from '@modern-js/builder-doc/docs/en/shared/rsbuild.md';
|
|
52
|
+
|
|
53
|
+
<Rsbuild />
|
|
54
|
+
|
|
49
55
|
## Rspack
|
|
50
56
|
|
|
51
57
|
import Rspack from '@modern-js/builder-doc/docs/en/shared/rspack.md';
|
|
File without changes
|
|
@@ -25,27 +25,18 @@ import InitRspackApp from '@site-docs/components/init-rspack-app';
|
|
|
25
25
|
:::tip
|
|
26
26
|
在使用 Rspack 作为打包工具时，由于部分能力尚在开发中，以下 features 暂时无法使用，我们将在未来提供支持：
|
|
27
27
|
|
|
28
|
-
- Storybook 调试
|
|
29
28
|
- 客户端渲染（CSR）使用 [useLoader](/guides/basic-features/data/data-fetch.html)
|
|
30
29
|
|
|
31
30
|
:::
|
|
32
31
|
|
|
33
32
|
## 开启 Rspack 构建
|
|
34
33
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
```bash
|
|
38
|
-
$ pnpm run new
|
|
39
|
-
? 请选择你想要的操作 启用可选功能
|
|
40
|
-
? 请选择功能名称 启用「Rspack 构建」
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
执行以上命令后，在 `modern.config.ts` 中添加 Rspack 相关配置即可：
|
|
34
|
+
从 Modern.js MAJOR_VERSION.46.0 版本起，在一个已有的 Modern.js 项目中，你仅需在 `modern.config.ts` 中添加以下配置，即可启用 Rspack 构建：
|
|
44
35
|
|
|
45
36
|
```diff title=modern.config.ts
|
|
46
37
|
import { appTools, defineConfig } from '@modern-js/app-tools';
|
|
47
38
|
|
|
48
|
-
|
|
39
|
+
export default defineConfig({
|
|
49
40
|
plugins: [
|
|
50
41
|
appTools({
|
|
51
42
|
+ bundler: 'experimental-rspack',
|
|
@@ -54,13 +45,70 @@ import { appTools, defineConfig } from '@modern-js/app-tools';
|
|
|
54
45
|
});
|
|
55
46
|
```
|
|
56
47
|
|
|
48
|
+
:::tip
|
|
49
|
+
如果你当前版本低于 MAJOR_VERSION.46.0, 可通过执行 `npx modern upgrade` 进行升级。
|
|
50
|
+
:::
|
|
51
|
+
|
|
57
52
|
import RspackPrecautions from '@modern-js/builder-doc/docs/zh/shared/rspackPrecautions.md';
|
|
58
53
|
|
|
59
54
|
<RspackPrecautions />
|
|
60
55
|
|
|
61
56
|
## 配置迁移
|
|
62
57
|
|
|
63
|
-
|
|
58
|
+
Modern.js 中 [tools.webpack](/configure/app/tools/webpack) 和 [tools.webpackChain](/configure/app/tools/webpack-chain) 配置仅在 webpack 模式下生效，开启 Rspack 构建能力后，可根据实际使用场景决定是否修改为 [tools.rspack](/configure/app/tools/rspack) 或 [tools.bundlerChain](/configure/app/tools/bundler-chain)。
|
|
59
|
+
|
|
60
|
+
```diff
|
|
61
|
+
export default {
|
|
62
|
+
tools: {
|
|
63
|
+
- webppack: (config, { env }) => {
|
|
64
|
+
+ rspack: (config, { env }) => {
|
|
65
|
+
if (env === 'development') {
|
|
66
|
+
config.devtool = 'cheap-module-eval-source-map';
|
|
67
|
+
}
|
|
68
|
+
return config;
|
|
69
|
+
},
|
|
70
|
+
- webpackChain: (chain, { env }) => {
|
|
71
|
+
+ bundlerChain: (chain, { env }) => {
|
|
72
|
+
if (env === 'development') {
|
|
73
|
+
chain.devtool('cheap-module-eval-source-map');
|
|
74
|
+
}
|
|
75
|
+
},
|
|
76
|
+
},
|
|
77
|
+
};
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
:::tip
|
|
82
|
+
开启 Rspack 构建能力后，目前有小部分配置在 Rspack 中还不支持使用，如 [source.moduleScopes](/configure/app/source/module-scopes)、[security.sri](/configure/app/security/sri) 等。
|
|
83
|
+
|
|
84
|
+
对于不支持的配置，我们在文档中有标注 `打包工具： 仅支持 webpack` 或 `打包工具： 仅支持 rspack`，可参考具体配置介绍。
|
|
85
|
+
:::
|
|
86
|
+
|
|
87
|
+
## 修改转译配置
|
|
88
|
+
|
|
89
|
+
Modern.js 在 Rspack 模式下使用 Rspack [builtin:swc-loader](https://www.rspack.dev/zh/guide/builtin-swc-loader.html) 进行代码转译。
|
|
90
|
+
|
|
91
|
+
Modern.js 已对 `builtin:swc-loader` 的常见配置提供了更方便的配置方式，如：通过 [source.transformImport](/configure/app/source/transform-import) 配置组件库按需引入。如果对 `builtin:swc-loader` 有自定义配置的需求，可参考以下代码：
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
export default {
|
|
95
|
+
tools: {
|
|
96
|
+
bundlerChain: (chain, { CHAIN_ID }) => {
|
|
97
|
+
chain.module
|
|
98
|
+
.rule(CHAIN_ID.RULE.JS)
|
|
99
|
+
.use(CHAIN_ID.USE.SWC)
|
|
100
|
+
.tap(options => {
|
|
101
|
+
options.xxx = '';
|
|
102
|
+
return options;
|
|
103
|
+
});
|
|
104
|
+
},
|
|
105
|
+
}
|
|
106
|
+
};
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
:::tip
|
|
110
|
+
在启用 Rspack 构建时，babel-loader 默认不会被启用。如需添加 babel 插件，可通过 [tools.babel](/configure/app/tools/babel) 配置，此时会产生额外的编译开销，在一定程度上拖慢 Rspack 构建速度。
|
|
111
|
+
:::
|
|
64
112
|
|
|
65
113
|
## Rspack 和 Modern.js 的版本关系
|
|
66
114
|
|
|
@@ -68,9 +116,9 @@ import RspackPrecautions from '@modern-js/builder-doc/docs/zh/shared/rspackPreca
|
|
|
68
116
|
|
|
69
117
|
但 Modern.js 对于 Rspack 的依赖方式为锁版本方式(非自动升级)，由于发版周期不同步等原因，可能会出现 Modern.js 内集成的 Rspack 版本落后于 Rspack 最新版本的情况。
|
|
70
118
|
|
|
71
|
-
当你执行 dev / build 命令时，Modern.js
|
|
119
|
+
当你执行 dev / build 命令时，Modern.js 会在[开启调试模式时](https://rsbuild.dev/zh/guide/debug/debug-mode)自动打印当前使用的 Rspack 版本：
|
|
72
120
|
|
|
73
|
-
|
|
74
122
|
|
|
75
123
|
#### 修改内置 Rspack 版本
|
|
76
124
|
|
|
@@ -84,7 +132,6 @@ import RspackPrecautions from '@modern-js/builder-doc/docs/zh/shared/rspackPreca
|
|
|
84
132
|
"overrides": {
|
|
85
133
|
"@rspack/core": "nightly",
|
|
86
134
|
"@rspack/plugin-react-refresh": "nightly",
|
|
87
|
-
"@rspack/plugin-html": "nightly"
|
|
88
135
|
}
|
|
89
136
|
}
|
|
90
137
|
}
|
|
@@ -232,9 +232,21 @@ function ErrorElement() {
|
|
|
232
232
|
}
|
|
233
233
|
```
|
|
234
234
|
|
|
235
|
+
## 为爬虫等待所有内容加载完毕
|
|
236
|
+
|
|
237
|
+
流式传输可以提高用户体验，因为当页面内容可用时，用户可以及时感知到它们。
|
|
238
|
+
|
|
239
|
+
然而，当一个爬虫访问该页面时，它可能需要先加载所有内容，直接输出整个 HTML，而不是渐进式地加载它。
|
|
240
|
+
|
|
241
|
+
Modern.js 使用 [isbot](https://www.npmjs.com/package/isbot) 对请求的 `uesr-agent`, 以判断请求是否来自爬虫。
|
|
242
|
+
|
|
235
243
|
:::info 补充信息
|
|
236
244
|
|
|
237
245
|
1. [Deferred Data](https://reactrouter.com/en/main/guides/deferred)
|
|
238
246
|
2. [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37)
|
|
239
247
|
|
|
240
248
|
:::
|
|
249
|
+
|
|
250
|
+
import StreamSSRPerformance from '@site-docs/components/stream-ssr-performance';
|
|
251
|
+
|
|
252
|
+
<StreamSSRPerformance />
|
|
@@ -6,7 +6,7 @@ sidebar_position: 14
|
|
|
6
6
|
|
|
7
7
|
[CSS Modules](https://github.com/css-modules/css-modules) 让我们能以模块化的方式编写 CSS 代码，并且可以在 JavaScript 文件中导入和使用这些样式。使用 CSS Modules 可以自动生成唯一的类名，隔离不同模块之间的样式，避免类名冲突。
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Modern.js 默认支持使用 CSS Modules，无需添加额外的配置。我们约定使用 `[name].module.css` 文件名来启用 CSS Modules。
|
|
10
10
|
|
|
11
11
|
以下样式文件会被视为 CSS Modules：
|
|
12
12
|
|
|
@@ -46,6 +46,12 @@ import ModuleFederation from '@modern-js/builder-doc/docs/zh/shared/module-feder
|
|
|
46
46
|
|
|
47
47
|
<ModuleFederation />
|
|
48
48
|
|
|
49
|
+
## Rsbuild
|
|
50
|
+
|
|
51
|
+
import Rsbuild from '@modern-js/builder-doc/docs/zh/shared/rsbuild.md';
|
|
52
|
+
|
|
53
|
+
<Rsbuild />
|
|
54
|
+
|
|
49
55
|
## Rspack
|
|
50
56
|
|
|
51
57
|
import Rspack from '@modern-js/builder-doc/docs/zh/shared/rspack.md';
|
package/package.json
CHANGED
|
@@ -15,17 +15,17 @@
|
|
|
15
15
|
"modern",
|
|
16
16
|
"modern.js"
|
|
17
17
|
],
|
|
18
|
-
"version": "2.
|
|
18
|
+
"version": "2.46.1",
|
|
19
19
|
"publishConfig": {
|
|
20
20
|
"registry": "https://registry.npmjs.org/",
|
|
21
21
|
"access": "public",
|
|
22
22
|
"provenance": true
|
|
23
23
|
},
|
|
24
24
|
"dependencies": {
|
|
25
|
-
"@modern-js/sandpack-react": "2.
|
|
25
|
+
"@modern-js/sandpack-react": "2.46.1"
|
|
26
26
|
},
|
|
27
27
|
"peerDependencies": {
|
|
28
|
-
"@modern-js/builder-doc": "^2.
|
|
28
|
+
"@modern-js/builder-doc": "^2.46.1"
|
|
29
29
|
},
|
|
30
30
|
"devDependencies": {
|
|
31
31
|
"classnames": "^2",
|
|
@@ -35,12 +35,12 @@
|
|
|
35
35
|
"ts-node": "^10.9.1",
|
|
36
36
|
"typescript": "^5",
|
|
37
37
|
"fs-extra": "^10",
|
|
38
|
-
"rspress": "1.
|
|
39
|
-
"@rspress/shared": "1.
|
|
38
|
+
"rspress": "1.10.0",
|
|
39
|
+
"@rspress/shared": "1.10.0",
|
|
40
40
|
"@types/node": "^16",
|
|
41
41
|
"@types/fs-extra": "9.0.13",
|
|
42
|
-
"@modern-js/doc
|
|
43
|
-
"@modern-js/
|
|
42
|
+
"@modern-js/builder-doc": "2.46.1",
|
|
43
|
+
"@modern-js/doc-plugin-auto-sidebar": "2.46.1"
|
|
44
44
|
},
|
|
45
45
|
"scripts": {
|
|
46
46
|
"dev": "rspress dev",
|