Skip to content

Commit 9f183ae

Browse files
Timeless0911Timeless0911
authored
docs: translate migration docs (#525)
1 parent ed55ef3 commit 9f183ae

File tree

6 files changed

+304
-33
lines changed

6 files changed

+304
-33
lines changed

‎website/docs/en/guide/migration/modernjs-module.mdx

Lines changed: 27 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,30 @@
1+
import { PackageManagerTabs } from '@theme';
2+
13
# Modern.js Module
24

3-
The migration path from `Modern.js Module` to `Rslib` is straightforward. The reason for it is the same underlying `Rsbuild` configuration.
5+
This section introduces how to migrate a project using Modern.js Module to Rslib.
46

57
## Adapt package.json
68

7-
`Rslib` has a minimal dependency footprint. For the basic functionality you only need the package `@rslib/core`. Let's update your `package.json` file.
9+
`Rslib` has a minimal dependency footprint. For the basic functionality you only need the package `@rslib/core`.
10+
11+
You can create a new Rslib project by following the [Quick Start](/guide/start/quick-start) to see the `package.json` file. Then update your existing `package.json` file like below:
812

913
- Remove the fields `main`, `lint-staged`, `simple-git-hooks`, `sideEffects` and `publishConfig`
1014
- Change the `types` field from `./dist/types/index.d.ts` to `./dist/index.d.ts`
1115
- Change the `module` field from `./dist/es/index.js` to `./dist/index.js`
1216
- Remove the scripts fields `prepare`, `build:watch`, `reset`, `change`, `bump`, `pre`, `change-status`, `gen-release-note`, `release`, `new`, `upgrade`
1317
- Change the script `build` from `modern build` to `rslib build`
18+
- Change the script `dev` from `modern dev` to `rslib build --watch`
1419
- Change the script `lint` name to `check` and keep the value
1520
- Add a new script `format` with the value `biome format --write`
16-
- Change the script `dev` from `modern dev` to `rslib build --watch`
1721
- Add the script `test` with the value `vitest run`
1822
- Add the field `exports` (object)
1923
- Add the field `"."` (object)
2024
- Add the fields `"types": "./dist/index.d.ts"` and `"import": "./dist/index.js"`
2125
- Add the field `files` with the value `["dist"]`
2226
- Depending on your configuration and use-case the `devDependencies` can vary
23-
- It is important to replace `"@modern-js/module-tools"` with `"@rslib/core"`
27+
- It is important to replace `@modern-js/module-tools` with `@rslib/core`
2428
- We do not need `rimraf`, `lint-staged` and `simple-git-hooks` anymore for starters
2529
- Copy over your required `dependencies` and `peerDependencies` if needed
2630

@@ -49,8 +53,9 @@ Your `package.json` should look something like this:
4953
},
5054
"devDependencies": {
5155
"@biomejs/biome": "^1.9.3",
52-
"@rslib/core": "^0.0.16",
53-
"typescript": "^5.6.3"
56+
"@rslib/core": "^0.1.3",
57+
"typescript": "^5.6.3",
58+
"vitest": "^2.1.8"
5459
},
5560
"peerDependencies": {},
5661
"dependencies": {}
@@ -59,7 +64,8 @@ Your `package.json` should look something like this:
5964

6065
## Adapt bundler config
6166

62-
Now we have a clean slate to work with. We will continue with the `Rslib` configuration. It follows the same pattern as all `Rs*` projects. Since this step is very unique for every environment, we will only touch the basics here:
67+
Now we have a clean slate to work with. We will continue with the `Rslib` configuration. It follows the same pattern as all `Rs*` projects. Since this step is very unique for every environment, below is an basic example:
68+
6369
Replace your `modern.config.ts` with a `rslib.config.ts`:
6470

6571
```js title="rslib.config.ts"
@@ -81,9 +87,9 @@ export default defineConfig({
8187
});
8288
```
8389

84-
## Typescript
90+
## TypeScript Declaration
8591

86-
If you use Typescript in your `Modern.js Module`, add the following changes:
92+
If you use Typescript in your `Modern.js Module` and need to generate declaration files, add the following changes:
8793

8894
```js title="rslib.config.ts"
8995
import { defineConfig } from '@rslib/core';
@@ -117,7 +123,9 @@ export default defineConfig({
117123
});
118124
```
119125

120-
In addition, you have to install the `@rsbuild/plugin-react` package as devDependency
126+
In addition, you have to install the `@rsbuild/plugin-react` package as `devDependencies`.
127+
128+
<PackageManagerTabs command="add @rsbuild/plugin-react -D" />
121129

122130
## Sass
123131

@@ -134,7 +142,9 @@ export default defineConfig({
134142
});
135143
```
136144

137-
In addition, you have to install the `@rsbuild/plugin-sass` package as devDependency.
145+
In addition, you have to install the `@rsbuild/plugin-sass` package as `devDependencies`.
146+
147+
<PackageManagerTabs command="add @rsbuild/plugin-sass -D" />
138148

139149
If you run Typescript together with Sass, you might run into DTS generation errors. This can be resolved by adding a `global.d.ts` file in your `/src` directory.
140150

@@ -168,3 +178,9 @@ export default defineConfig({
168178
plugins: [pluginSass()],
169179
});
170180
```
181+
182+
## Contents Supplement
183+
184+
This migration doc is contributed by community user [YanPes](https://github.com/YanPes). Much appreciation for his contribution!
185+
186+
Rslib is designed to be next generation of Modern.js Module and we will provide more detailed guide and scripts for migration in 2025 Q1.

‎website/docs/en/guide/migration/tsup.mdx

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import { PackageManagerTabs } from '@theme';
1616

1717
<PackageManagerTabs command="add @rslib/core -D" />
1818

19-
## Updating npm scripts
19+
## Updating npm Scripts
2020

2121
Next, you need to update the npm scripts in your package.json to use Rslib's CLI commands.
2222

@@ -33,7 +33,7 @@ Next, you need to update the npm scripts in your package.json to use Rslib's CLI
3333

3434
## Create Configuration File
3535

36-
Create a Rslib configuration file `rslib.config.ts` in the same directory as package.json, and add the following content:
36+
Create a Rslib configuration file `rslib.config.ts` in the same directory as `package.json`, and add the following content:
3737

3838
```ts title="rslib.config.ts"
3939
import { defineConfig } from '@rslib/core';
@@ -45,24 +45,24 @@ export default defineConfig({});
4545

4646
Here is the corresponding Rslib configuration for tsup configuration:
4747

48-
| tsup | Rslib |
49-
| ------------- | ------------------------------------------------------------------------------------------ |
50-
| banner | [lib.banner](/config/lib/banner) |
51-
| bundle | [lib.bundle](/config/lib/bundle) |
52-
| clean | [output.cleanDistPath](/config/rsbuild/output) |
53-
| define | [source.define](/config/rsbuild/source) |
54-
| dts | [lib.dts](/config/lib/dts) |
55-
| entry | [source.entry](/config/rsbuild/source) |
56-
| external | [output.externals](/config/rsbuild/output) / [lib.autoExternal](/config/lib/auto-external) |
57-
| format | [lib.format](/config/lib/format) |
58-
| footer | [lib.footer](/config/lib/footer) |
59-
| minify | [output.minify](/config/rsbuild/output) |
60-
| platform | [output.target](/config/rsbuild/output) |
61-
| plugins | [plugins](/config/rsbuild/plugins) |
62-
| sourcemap | [output.sourceMap](/config/rsbuild/output) |
63-
| shims | [lib.shims](/config/lib/shims) |
64-
| terserOptions | [output.minify](/config/rsbuild/output) |
65-
| tsconfig | [source.tsconfigPath](/config/rsbuild/source) |
48+
| tsup | Rslib |
49+
| ------------- | ---------------------------------------------------------------------------------------------------------- |
50+
| banner | [lib.banner](/config/lib/banner) |
51+
| bundle | [lib.bundle](/config/lib/bundle) |
52+
| clean | [output.cleanDistPath](/config/rsbuild/output#outputcleandistpath) |
53+
| define | [source.define](/config/rsbuild/source#sourcedefine) |
54+
| dts | [lib.dts](/config/lib/dts) |
55+
| entry | [source.entry](/config/rsbuild/source#sourceentry) |
56+
| external | [output.externals](/config/rsbuild/output#outputexternals) / [lib.autoExternal](/config/lib/auto-external) |
57+
| format | [lib.format](/config/lib/format) |
58+
| footer | [lib.footer](/config/lib/footer) |
59+
| minify | [output.minify](/config/rsbuild/output#outputminify) |
60+
| platform | [output.target](/config/rsbuild/output#outputtarget) |
61+
| plugins | [plugins](/config/rsbuild/plugins) |
62+
| sourcemap | [output.sourceMap](/config/rsbuild/output#outputsourcemap) |
63+
| shims | [lib.shims](/config/lib/shims) |
64+
| terserOptions | [output.minify](/config/rsbuild/output#outputminify) |
65+
| tsconfig | [source.tsconfigPath](/config/rsbuild/source#sourcetsconfigpath) |
6666

6767
## Contents Supplement
6868

‎website/docs/zh/guide/advanced/output-compatibility.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Rslib 还支持使用 [.browserslistrc](https://github.com/browserslist/browsers
1515

1616
## Polyfill
1717

18-
在处理兼容性问题之前，建议了解以下背景知识，以便更好地处理相关问题。请查看有关[语法降级和 API 降级](https://rsbuild.dev/zh/guide/advanced/browser-compatibility#%E8%AF%AD%E6%B3%95%E9%99%8D%E7%BA%A7%E5%92%8C-api-%E9%99%8D%E7%BA%A7)的背景知识。
18+
在处理兼容性问题之前，建议了解以下背景知识，以便更好地处理相关问题。请查看有关 [语法降级和 API 降级](https://rsbuild.dev/zh/guide/advanced/browser-compatibility#%E8%AF%AD%E6%B3%95%E9%99%8D%E7%BA%A7%E5%92%8C-api-%E9%99%8D%E7%BA%A7) 的背景知识。
1919

2020
### 浏览器
2121

‎website/docs/zh/guide/basic/output-structure.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
首先让我们了解一下 bundle 和 bundleless。
66

7-
所谓 bundle 是指对构建产物进行打包，构建产物可能是一个文件，也有可能是基于一定的[代码拆分策略](https://esbuild.github.io/api/#splitting)得到的多个文件。
7+
所谓 bundle 是指对构建产物进行打包，构建产物可能是一个文件，也有可能是基于一定的 [代码拆分策略](https://esbuild.github.io/api/#splitting) 得到的多个文件。
88

99
而 bundleless，则是指对每个源文件单独进行编译构建，但是并不将它们打包在一起。每一个产物文件都可以找到与之相对应的源码文件。bundleless 构建的过程，也可以理解为仅对源文件进行代码转换的过程。
1010

‎website/docs/zh/guide/migration/modernjs-module.mdx

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,186 @@
1+
import { PackageManagerTabs } from '@theme';
2+
13
# Modern.js Module
4+
5+
本章节介绍如何将使用 Modern.js Module 的项目迁移到 Rslib。
6+
7+
## 调整 package.json
8+
9+
`Rslib` 的依赖链路非常短。对于基本功能，你只需要使用 `@rslib/core` 包。
10+
11+
你可以通过 [快速开始](/guide/start/quick-start) 创建一个 Rslib 项目，然后更新你的 `package.json` 文件，如下所示：
12+
13+
- 移除 `main`, `lint-staged`, `simple-git-hooks`, `sideEffects` 和 `publishConfig` 字段
14+
- 将 `types` 字段从 `./dist/types/index.d.ts` 改为 `./dist/index.d.ts`
15+
- 将 `module` 字段从 `./dist/es/index.js` 改为 `./dist/index.js`
16+
- 移除 `prepare`, `build:watch`, `reset`, `change`, `bump`, `pre`, `change-status`, `gen-release-note`, `release`, `new`, `upgrade` 脚本
17+
- 将 `build` 脚本从 `modern build` 改为 `rslib build`
18+
- 将 `dev` 脚本从 `modern dev` 改为 `rslib build --watch`
19+
- 将 `lint` 脚本名称改为 `check` 并保持其值
20+
- 添加一个新脚本 `format` 并设置其值为 `biome format --write`
21+
- 添加一个新脚本 `test` 并设置其值为 `vitest run`
22+
- 添加 `exports` 字段 (object)
23+
- 添加 `"."` (object)
24+
- 添加 `"types": "./dist/index.d.ts"` 和 `"import": "./dist/index.js"` 字段
25+
- 添加 `files` 字段并设置其值为 `["dist"]`
26+
- 根据你的配置和使用情况，`devDependencies` 可能会有所不同
27+
- 重要提示：将 `@modern-js/module-tools` 替换为 `@rslib/core`
28+
- 我们不再需要 `rimraf`, `lint-staged` 和 `simple-git-hooks` 了
29+
- 复制你需要的 `dependencies` 和 `peerDependencies` 字段
30+
31+
你的 `package.json` 文件应该如下所示：
32+
33+
```json title="package.json"
34+
{
35+
"name": "rslib",
36+
"version": "1.0.0",
37+
"type": "module",
38+
"exports": {
39+
".": {
40+
"types": "./dist/index.d.ts",
41+
"import": "./dist/index.js"
42+
}
43+
},
44+
"module": "./dist/index.js",
45+
"types": "./dist/index.d.ts",
46+
"files": ["dist"],
47+
"scripts": {
48+
"build": "rslib build",
49+
"check": "biome check --write",
50+
"dev": "rslib build --watch",
51+
"format": "biome format --write",
52+
"test": "vitest run"
53+
},
54+
"devDependencies": {
55+
"@biomejs/biome": "^1.9.3",
56+
"@rslib/core": "^0.1.3",
57+
"typescript": "^5.6.3",
58+
"vitest": "^2.1.8"
59+
},
60+
"peerDependencies": {},
61+
"dependencies": {}
62+
}
63+
```
64+
65+
## 调整打包配置
66+
67+
现在我们有了一个干净的起点。我们将继续使用 `Rslib` 配置。它遵循所有 `Rs*` 项目的相同模式。由于此步骤对于每个人来说都不同，下面是一个基本的示例：
68+
69+
将你的 `modern.config.ts` 文件替换为 `rslib.config.ts` 文件：
70+
71+
```js title="rslib.config.ts"
72+
import { defineConfig } from '@rslib/core';
73+
74+
export default defineConfig({
75+
source: {
76+
entry: {
77+
index: ['./src/**'],
78+
},
79+
},
80+
lib: [
81+
{
82+
bundle: false,
83+
dts: true,
84+
format: 'esm',
85+
},
86+
],
87+
});
88+
```
89+
90+
## TypeScript 类型定义
91+
92+
如果你在 `Modern.js Module` 中使用 Typescript 并需要生成类型定义文件，请添加以下更改：
93+
94+
```js title="rslib.config.ts"
95+
import { defineConfig } from '@rslib/core';
96+
97+
export default defineConfig({
98+
//...
99+
lib: [
100+
{
101+
//...
102+
dts: true,
103+
},
104+
],
105+
});
106+
```
107+
108+
## React
109+
110+
如果你在 `Modern.js Module` 中使用 React，请添加以下更改：
111+
112+
```js title="rslib.config.ts"
113+
import { defineConfig } from '@rslib/core';
114+
// 快速提示：你可以在这里使用所有 Rsbuild 插件，因为它们与 Rslib 兼容
115+
import { pluginReact } from '@rsbuild/plugin-react';
116+
117+
export default defineConfig({
118+
//...
119+
output: {
120+
target: 'web',
121+
},
122+
plugins: [pluginReact()],
123+
});
124+
```
125+
126+
此外，你需要安装 `@rsbuild/plugin-react` 包作为 `devDependencies`。
127+
128+
<PackageManagerTabs command="add @rsbuild/plugin-react -D" />
129+
130+
## Sass
131+
132+
如果你在 `Modern.js Module` 中使用 Sass，请添加以下更改：
133+
134+
```js title="rslib.config.ts"
135+
import { defineConfig } from '@rslib/core';
136+
// 快速提示：你可以在这里使用所有 Rsbuild 插件，因为它们与 Rslib 兼容
137+
import { pluginSass } from '@rsbuild/plugin-sass';
138+
139+
export default defineConfig({
140+
//...
141+
plugins: [pluginSass()],
142+
});
143+
```
144+
145+
此外，你需要安装 `@rsbuild/plugin-sass` 包作为 `devDependencies`。
146+
147+
<PackageManagerTabs command="add @rsbuild/plugin-sass -D" />
148+
149+
如果你在运行 Typescript 和 Sass，你可能会遇到 DTS 生成错误。这可以通过在 `/src` 目录中添加一个 `global.d.ts` 文件来解决。
150+
151+
```ts title="global.d.ts"
152+
declare module '*.scss' {
153+
const content: { [className: string]: string };
154+
export default content;
155+
}
156+
```
157+
158+
## CSS Modules
159+
160+
如果你在 `Modern.js Module` 中使用 CSS Modules，请添加以下更改：
161+
162+
```js title="rslib.config.ts"
163+
import { defineConfig } from '@rslib/core';
164+
import { pluginSass } from '@rsbuild/plugin-sass';
165+
166+
export default defineConfig({
167+
lib: [
168+
{
169+
//...
170+
output: {
171+
cssModules: {
172+
// CSS Modules 选项与官方 "css-modules" 包中的选项完全相同
173+
localIdentName: '[local]--[hash:base64:5]',
174+
},
175+
},
176+
},
177+
],
178+
plugins: [pluginSass()],
179+
});
180+
```
181+
182+
## 内容补充
183+
184+
此迁移文档由社区用户 [YanPes](https://github.com/YanPes) 贡献。非常感谢他的贡献！
185+
186+
Rslib 旨在成为 Modern.js Module 的下一代解决方案，我们将在 2025 年第一季度提供更多详细的迁移指南和脚本。

0 commit comments

Comments
 (0)