@modern-js/main-doc 3.3.0 → 3.5.0
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/community/blog/v3-release-note.mdx +1 -1
- package/docs/en/configure/app/experiments/source-build.mdx +1 -1
- package/docs/en/configure/app/html/template-parameters.mdx +1 -1
- package/docs/en/configure/app/output/convert-to-rem.mdx +1 -1
- package/docs/en/configure/app/security/check-syntax.mdx +1 -1
- package/docs/en/configure/app/tools/html-plugin.mdx +1 -1
- package/docs/en/configure/app/tools/ts-checker.mdx +40 -14
- package/docs/en/guides/advanced-features/page-performance/optimize-bundle.mdx +1 -1
- package/docs/en/guides/basic-features/debug/using-storybook.mdx +1 -1
- package/docs/en/guides/basic-features/static-assets/json-files.mdx +2 -2
- package/docs/en/guides/basic-features/testing/rstest.mdx +29 -0
- package/docs/en/guides/get-started/_meta.json +8 -1
- package/docs/en/guides/get-started/ai-coding-agents.mdx +48 -0
- package/docs/en/guides/upgrade/config.mdx +1 -1
- package/docs/en/plugin/introduction.mdx +9 -9
- package/docs/zh/community/blog/v3-release-note.mdx +1 -1
- package/docs/zh/configure/app/experiments/source-build.mdx +1 -1
- package/docs/zh/configure/app/html/template-parameters.mdx +1 -1
- package/docs/zh/configure/app/output/convert-to-rem.mdx +1 -1
- package/docs/zh/configure/app/security/check-syntax.mdx +1 -1
- package/docs/zh/configure/app/tools/html-plugin.mdx +1 -1
- package/docs/zh/configure/app/tools/ts-checker.mdx +39 -13
- package/docs/zh/guides/advanced-features/page-performance/optimize-bundle.mdx +1 -1
- package/docs/zh/guides/basic-features/debug/using-storybook.mdx +1 -1
- package/docs/zh/guides/basic-features/static-assets/json-files.mdx +2 -2
- package/docs/zh/guides/basic-features/testing/rstest.mdx +29 -0
- package/docs/zh/guides/get-started/_meta.json +8 -1
- package/docs/zh/guides/get-started/ai-coding-agents.mdx +48 -0
- package/docs/zh/guides/upgrade/config.mdx +1 -1
- package/docs/zh/plugin/introduction.mdx +9 -9
- package/package.json +2 -2
|
@@ -591,7 +591,7 @@ As Node.js continues to evolve, Node.js 18 has reached EOL. In Modern.js 3.0, we
|
|
|
591
591
|
|
|
592
592
|
#### Storybook Rsbuild
|
|
593
593
|
|
|
594
|
-
In Modern.js 3.0, we implemented Storybook for Modern.js applications based on [Storybook Rsbuild](https://github.com/
|
|
594
|
+
In Modern.js 3.0, we implemented Storybook for Modern.js applications based on [Storybook Rsbuild](https://github.com/rstackjs/storybook-rsbuild).
|
|
595
595
|
|
|
596
596
|
Through a Storybook Addon, we convert and merge Modern.js configuration into Rsbuild configuration, and use Storybook Rsbuild to drive the build, keeping Storybook debugging aligned with development command configurations.
|
|
597
597
|
|
|
@@ -19,7 +19,7 @@ More detail can see ["Source Code Build Mode"](https://modernjs.dev/en/guides/ad
|
|
|
19
19
|
|
|
20
20
|
### Options
|
|
21
21
|
|
|
22
|
-
`experiments.sourceBuild` is implemented based on [@rsbuild/plugin-source-build](https://github.com/
|
|
22
|
+
`experiments.sourceBuild` is implemented based on [@rsbuild/plugin-source-build](https://github.com/rstackjs/rsbuild-plugin-source-build?tab=readme-ov-file#options). You can pass plugin options like this:
|
|
23
23
|
|
|
24
24
|
```ts
|
|
25
25
|
export default {
|
|
@@ -30,7 +30,7 @@ type DefaultParameters = {
|
|
|
30
30
|
};
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
-
Define the parameters in the HTML template, corresponding to the `templateParameters` config of [html-rspack-plugin](https://github.com/
|
|
33
|
+
Define the parameters in the HTML template, corresponding to the `templateParameters` config of [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin). You can use the config as an object or a function.
|
|
34
34
|
|
|
35
35
|
import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
|
|
36
36
|
|
|
@@ -70,4 +70,4 @@ If a syntax error is detected, you can handle it in the following ways:
|
|
|
70
70
|
|
|
71
71
|
### Options
|
|
72
72
|
|
|
73
|
-
`security.checkSyntax` is implemented based on `@rsbuild/plugin-check-syntax`. For specific options, please refer to [@rsbuild/plugin-check-syntax](https://github.com/
|
|
73
|
+
`security.checkSyntax` is implemented based on `@rsbuild/plugin-check-syntax`. For specific options, please refer to [@rsbuild/plugin-check-syntax](https://github.com/rstackjs/rsbuild-plugin-check-syntax).
|
|
@@ -38,7 +38,7 @@ const defaultOptions = {
|
|
|
38
38
|
SSR Application does not enable the `minify.removeComments` configuration, otherwise the SSR rendering will fail.
|
|
39
39
|
:::
|
|
40
40
|
|
|
41
|
-
The configs of [html-rspack-plugin](https://github.com/
|
|
41
|
+
The configs of [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) can be modified through `tools.htmlPlugin`.
|
|
42
42
|
|
|
43
43
|
import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
|
|
44
44
|
|
|
@@ -12,20 +12,21 @@ import { PackageManagerTabs } from '@theme';
|
|
|
12
12
|
```js
|
|
13
13
|
const defaultOptions = {
|
|
14
14
|
typescript: {
|
|
15
|
+
// set 'readonly' to avoid emitting tsbuildinfo,
|
|
16
|
+
// as the generated tsbuildinfo will break ts-checker-rspack-plugin
|
|
17
|
+
mode: 'readonly',
|
|
18
|
+
// enable build when using project reference
|
|
19
|
+
build: useReference,
|
|
15
20
|
// avoid OOM issue
|
|
16
21
|
memoryLimit: 8192,
|
|
17
22
|
// use tsconfig of user project
|
|
18
23
|
configFile: tsconfigPath,
|
|
19
|
-
//
|
|
20
|
-
|
|
21
|
-
// use typescript of user project
|
|
22
|
-
typescriptPath: require.resolve('typescript'),
|
|
24
|
+
// resolve the default TypeScript package from user project
|
|
25
|
+
resolveRoot: rootPath,
|
|
23
26
|
},
|
|
24
27
|
issue: {
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
{ file: '**/node_modules/**/*' },
|
|
28
|
-
],
|
|
28
|
+
// ignore type errors from node_modules
|
|
29
|
+
exclude: [({ file = '' }) => /[\\/]node_modules[\\/]/.test(file)],
|
|
29
30
|
},
|
|
30
31
|
logger: {
|
|
31
32
|
log() {
|
|
@@ -33,7 +34,11 @@ const defaultOptions = {
|
|
|
33
34
|
// we only want to display error messages
|
|
34
35
|
},
|
|
35
36
|
error(message: string) {
|
|
36
|
-
console.error(
|
|
37
|
+
console.error(
|
|
38
|
+
message
|
|
39
|
+
.replace(/ERROR/g, 'Type Error')
|
|
40
|
+
.replace(/WARNING/g, 'Type Warning'),
|
|
41
|
+
);
|
|
37
42
|
},
|
|
38
43
|
},
|
|
39
44
|
},
|
|
@@ -43,7 +48,9 @@ By default, the [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild
|
|
|
43
48
|
|
|
44
49
|
## Example
|
|
45
50
|
|
|
46
|
-
|
|
51
|
+
### Object Type
|
|
52
|
+
|
|
53
|
+
When the value of `tsChecker` is an object, it will be deeply merged with the default configuration.
|
|
47
54
|
|
|
48
55
|
```ts
|
|
49
56
|
export default {
|
|
@@ -57,17 +64,34 @@ export default {
|
|
|
57
64
|
};
|
|
58
65
|
```
|
|
59
66
|
|
|
67
|
+
### Function Type
|
|
68
|
+
|
|
69
|
+
When the value of `tsChecker` is a function, the default configuration will be passed as the first argument. You can directly modify the configuration object or return an object as the final configuration.
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
export default {
|
|
73
|
+
tools: {
|
|
74
|
+
tsChecker(options) {
|
|
75
|
+
options.async = false;
|
|
76
|
+
return options;
|
|
77
|
+
},
|
|
78
|
+
},
|
|
79
|
+
};
|
|
80
|
+
```
|
|
81
|
+
|
|
60
82
|
> Please refer to [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) for more details.
|
|
61
83
|
|
|
62
84
|
## TypeScript Go Support
|
|
63
85
|
|
|
64
86
|
`tools.tsChecker` supports enabling [TypeScript Go](https://github.com/microsoft/typescript-go) for type checking. This experimental capability is provided by [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin), which is integrated by [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check), and can reduce type-checking time by about 5-10x.
|
|
65
87
|
|
|
66
|
-
|
|
88
|
+
Install TypeScript 7.0 RC to enable TypeScript Go automatically:
|
|
67
89
|
|
|
68
|
-
<PackageManagerTabs command="install @
|
|
90
|
+
<PackageManagerTabs command="install typescript@rc -D" />
|
|
69
91
|
|
|
70
|
-
|
|
92
|
+
You can also install `@typescript/native-preview` and set `typescript.tsgo` to `true`:
|
|
93
|
+
|
|
94
|
+
<PackageManagerTabs command="install @typescript/native-preview -D" />
|
|
71
95
|
|
|
72
96
|
```ts
|
|
73
97
|
export default {
|
|
@@ -81,6 +105,8 @@ export default {
|
|
|
81
105
|
};
|
|
82
106
|
```
|
|
83
107
|
|
|
84
|
-
When `tsgo` is enabled
|
|
108
|
+
When `tsgo` is enabled and `typescript.typescriptPath` is set manually, it must point to an absolute `typescript/package.json` path from TypeScript 7+ or `@typescript/native-preview/package.json`.
|
|
109
|
+
|
|
110
|
+
> The `@typescript/native-preview` usage is deprecated and kept only for compatibility. We recommend installing `typescript@rc` to use `tsgo`.
|
|
85
111
|
|
|
86
112
|
For supported options and limitations, please refer to [ts-checker-rspack-plugin - TypeScript Go support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-go-support).
|
|
@@ -92,7 +92,7 @@ export default {
|
|
|
92
92
|
};
|
|
93
93
|
```
|
|
94
94
|
|
|
95
|
-
See details in [plugin-image-compress](https://github.com/
|
|
95
|
+
See details in [plugin-image-compress](https://github.com/rstackjs/rsbuild-plugin-image-compress).
|
|
96
96
|
|
|
97
97
|
## Split Chunk
|
|
98
98
|
|
|
@@ -97,4 +97,4 @@ Now you can request the path configured in `bff.prefix`; if not configured, use
|
|
|
97
97
|
|
|
98
98
|
## Example
|
|
99
99
|
|
|
100
|
-
You can check out the [example](https://github.com/
|
|
100
|
+
You can check out the [example](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react) to learn how to use Storybook in Modern.js.
|
|
@@ -38,7 +38,7 @@ import { name } from './example.json';
|
|
|
38
38
|
|
|
39
39
|
YAML is a data serialization language commonly used for writing configuration files.
|
|
40
40
|
|
|
41
|
-
You can configure the [YAML plugin](https://github.com/
|
|
41
|
+
You can configure the [YAML plugin](https://github.com/rstackjs/rsbuild-plugin-yaml) in `modern.config.ts` to support importing `.yaml` or `.yml` files, they will be automatically converted to JSON format.
|
|
42
42
|
|
|
43
43
|
```ts
|
|
44
44
|
import { defineConfig } from '@modern-js/app-tools';
|
|
@@ -85,7 +85,7 @@ declare module '*.yml' {
|
|
|
85
85
|
|
|
86
86
|
Toml is a semantically explicit, easy-to-read configuration file format.
|
|
87
87
|
|
|
88
|
-
You can configure the [TOML plugin](https://github.com/
|
|
88
|
+
You can configure the [TOML plugin](https://github.com/rstackjs/rsbuild-plugin-toml) in `modern.config.ts` to support importing `.toml` files, it will be automatically converted to JSON format.
|
|
89
89
|
|
|
90
90
|
```ts
|
|
91
91
|
import { defineConfig } from '@modern-js/app-tools';
|
|
@@ -8,6 +8,7 @@ This guide explains how to integrate Rstest with Modern.js for web app testing.
|
|
|
8
8
|
|
|
9
9
|
Install the base dependencies first:
|
|
10
10
|
|
|
11
|
+
import { Prompt } from '@rspress/core/theme';
|
|
11
12
|
import { PackageManagerTabs } from '@theme';
|
|
12
13
|
|
|
13
14
|
<PackageManagerTabs command="add @rstest/core @modern-js/adapter-rstest -D" />
|
|
@@ -161,3 +162,31 @@ Execute the `test` command above to run your tests:
|
|
|
161
162
|
If you need node mode tests for server-side logic such as `bff`, refer to the [Rstest documentation](https://rstest.rs) directly.
|
|
162
163
|
|
|
163
164
|
Modern.js mainly targets web apps, so this guide focuses on web UI testing and browser mode.
|
|
165
|
+
|
|
166
|
+
## Migrating from Existing Projects
|
|
167
|
+
|
|
168
|
+
If your project already uses Jest or Vitest, refer to the official Rstest migration guides:
|
|
169
|
+
|
|
170
|
+
- [Migrate from Jest to Rstest](https://rstest.rs/guide/migration/jest)
|
|
171
|
+
- [Migrate from Vitest to Rstest](https://rstest.rs/guide/migration/vitest)
|
|
172
|
+
|
|
173
|
+
We recommend installing the `migrate-to-rstest` skill first, then copying this prompt to your coding agent. It keeps the Modern.js `@modern-js/adapter-rstest` integration during migration:
|
|
174
|
+
|
|
175
|
+
<Prompt
|
|
176
|
+
title="Migrate to Rstest"
|
|
177
|
+
description="Copy this prompt and send it to your coding agent."
|
|
178
|
+
prompt={`Migrate this Modern.js project from Jest or Vitest to Rstest.
|
|
179
|
+
|
|
180
|
+
First install and use the migrate-to-rstest skill. If it is not installed, install it with:
|
|
181
|
+
npx skills add rstackjs/agent-skills --skill migrate-to-rstest
|
|
182
|
+
|
|
183
|
+
Follow the migrate-to-rstest skill instructions and the official Rstest migration guides:
|
|
184
|
+
- Jest: https://rstest.rs/guide/migration/jest
|
|
185
|
+
- Vitest: https://rstest.rs/guide/migration/vitest
|
|
186
|
+
|
|
187
|
+
Modern.js-specific requirement:
|
|
188
|
+
- Install and use @modern-js/adapter-rstest together with @rstest/core.
|
|
189
|
+
- Create or update rstest.config.ts to import withModernConfig from @modern-js/adapter-rstest.
|
|
190
|
+
- Reuse the Modern.js app configuration with extends: withModernConfig().
|
|
191
|
+
- Do not replace this with a plain Rstest config unless the project explicitly does not need Modern.js config integration.`}
|
|
192
|
+
/>
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: AI Tools
|
|
3
|
+
sidebar_position: 6
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Modern.js For AI
|
|
7
|
+
|
|
8
|
+
Modern.js provides a toolkit for AI agents that helps developers use AI to efficiently complete feature development, dependency upgrades, and version migration for Modern.js applications.
|
|
9
|
+
|
|
10
|
+
## llms.txt
|
|
11
|
+
|
|
12
|
+
Modern.js docs follow the [llms.txt specification](https://llmstxt.org/), auto-generated by [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms), accessible via `/llms.txt` or `/llms-full.txt`:
|
|
13
|
+
|
|
14
|
+
- Index: [`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
|
|
15
|
+
- Full text: `https://modernjs.dev/llms-full.txt` (large — fetch on demand)
|
|
16
|
+
|
|
17
|
+
Most "what is this API / config" questions can be answered from llms.txt. Just let your agent retrieve it on demand; no need to copy docs into your project.
|
|
18
|
+
|
|
19
|
+
## Skills
|
|
20
|
+
|
|
21
|
+
Skills are on-demand AI capabilities following the [Agent Skills open standard](https://github.com/vercel-labs/skills). User-facing Skills:
|
|
22
|
+
|
|
23
|
+
| Skill | Identifier | Description |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| Upgrade to v3 | `modernjs-migrate-to-v3` | Migrate a v2 app to v3: safe rewrites + manual checklist + migration report |
|
|
26
|
+
| Enable features | `modernjs-feature-enable` | Enable BFF / SSG / styled-components for v3 apps, and scaffold Tailwind CSS / custom Web Server |
|
|
27
|
+
|
|
28
|
+
> Skills are not force-installed or implicitly installed — you install them explicitly. RSC and micro-frontend setups are configuration or architecture decisions, not one-click `modernjs-feature-enable` actions.
|
|
29
|
+
|
|
30
|
+
## Installing Skills
|
|
31
|
+
|
|
32
|
+
Modern.js user-facing Skills live in the repo's root `skills/` directory and follow the [Agent Skills open standard](https://github.com/vercel-labs/skills). The recommended way is the standard `skills` CLI, installing straight from GitHub:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
# List installable Skills
|
|
36
|
+
npx skills add web-infra-dev/modern.js --list
|
|
37
|
+
|
|
38
|
+
# Install a single Skill into your agent directory (--agent: claude-code / codex / cursor / ...)
|
|
39
|
+
npx skills add web-infra-dev/modern.js --skill modernjs-migrate-to-v3 --agent codex -y
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
It installs the entire Skill directory (`SKILL.md` + `scripts/` + `references/`) into the corresponding agent directory, ready to trigger there.
|
|
43
|
+
|
|
44
|
+
> To pin a specific version, append `#<ref>` (a tag, branch, or commit) to the repo — it installs the Skill as of that ref (replace `<tag>` with a release tag that contains this Skill):
|
|
45
|
+
>
|
|
46
|
+
> ```bash
|
|
47
|
+
> npx skills add web-infra-dev/modern.js#<tag> --skill modernjs-migrate-to-v3 --agent codex -y
|
|
48
|
+
> ```
|
|
@@ -314,7 +314,7 @@ export default {
|
|
|
314
314
|
|
|
315
315
|
### tools.pug
|
|
316
316
|
|
|
317
|
-
**Change**: This configuration has been deprecated, use Rsbuild's [Pug plugin](https://github.com/
|
|
317
|
+
**Change**: This configuration has been deprecated, use Rsbuild's [Pug plugin](https://github.com/rstackjs/rsbuild-plugin-pug) to enable support.
|
|
318
318
|
|
|
319
319
|
**Migration Example**:
|
|
320
320
|
|
|
@@ -131,21 +131,21 @@ The following are official Rsbuild plugins that are already built into Modern.js
|
|
|
131
131
|
| [React Plugin](https://v2.rsbuild.rs/plugins/list/plugin-react) | Provides support for React | - |
|
|
132
132
|
| [SVGR Plugin](https://v2.rsbuild.rs/plugins/list/plugin-svgr) | Supports converting SVG images into React components | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export) |
|
|
133
133
|
| [Assets Retry Plugin](https://github.com/rstackjs/rsbuild-plugin-assets-retry) | Automatically retries requests when static asset loading fails | [output.assetsRetry](/configure/app/output/assets-retry.html) |
|
|
134
|
-
| [Type Check Plugin](https://github.com/
|
|
135
|
-
| [Source Build Plugin](https://github.com/
|
|
136
|
-
| [Check Syntax Plugin](https://github.com/
|
|
137
|
-
| [CSS Minimizer Plugin](https://github.com/
|
|
138
|
-
| [Rem Plugin](https://github.com/
|
|
134
|
+
| [Type Check Plugin](https://github.com/rstackjs/rsbuild-plugin-type-check) | Runs TypeScript type checking in a separate process | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
|
|
135
|
+
| [Source Build Plugin](https://github.com/rstackjs/rsbuild-plugin-source-build) | For monorepo scenarios, supports referencing source code from other subdirectories and completing builds and hot updates | [experiments.sourceBuild](/configure/app/experiments/source-build.html) |
|
|
136
|
+
| [Check Syntax Plugin](https://github.com/rstackjs/rsbuild-plugin-check-syntax) | Analyzes the syntax compatibility of the build artifacts to determine if there are any advanced syntax features that cause compatibility issues | [security.checkSyntax](/configure/app/security/check-syntax.html) |
|
|
137
|
+
| [CSS Minimizer Plugin](https://github.com/rstackjs/rsbuild-plugin-css-minimizer) | Used to customize the CSS compression tool, switch to [cssnano](https://cssnano.co/) or other tools for CSS compression | [tools.minifyCss](/configure/app/tools/minify-css.html) |
|
|
138
|
+
| [Rem Plugin](https://github.com/rstackjs/rsbuild-plugin-rem) | Implements rem adaptive layout for mobile pages | [output.convertToRem](/configure/app/output/convert-to-rem.html) |
|
|
139
139
|
|
|
140
140
|
#### Plugins Not Built-in
|
|
141
141
|
|
|
142
142
|
The following are official Rsbuild plugins that are not built into Modern.js:
|
|
143
143
|
|
|
144
|
-
- [Image Compress Plugin](https://github.com/
|
|
144
|
+
- [Image Compress Plugin](https://github.com/rstackjs/rsbuild-plugin-image-compress): Compresses image resources used in the project.
|
|
145
145
|
- [Stylus Plugin](https://v2.rsbuild.rs/plugins/list/plugin-stylus): Uses Stylus as the CSS preprocessor.
|
|
146
|
-
- [UMD Plugin](https://github.com/
|
|
147
|
-
- [YAML Plugin](https://github.com/
|
|
148
|
-
- [TOML Plugin](https://github.com/
|
|
146
|
+
- [UMD Plugin](https://github.com/rstackjs/rsbuild-plugin-umd): Used to build UMD format artifacts.
|
|
147
|
+
- [YAML Plugin](https://github.com/rstackjs/rsbuild-plugin-yaml): Used to reference YAML files and convert them to JavaScript objects.
|
|
148
|
+
- [TOML Plugin](https://github.com/rstackjs/rsbuild-plugin-toml): Used to reference TOML files and convert them to JavaScript objects.
|
|
149
149
|
|
|
150
150
|
import OtherPlugins from '@site-docs-en/components/other-plugins.mdx';
|
|
151
151
|
|
|
@@ -591,7 +591,7 @@ Modern.js 3.0 新项目默认使用 React 19，最低支持 React 18。
|
|
|
591
591
|
|
|
592
592
|
#### Storybook Rsbuild
|
|
593
593
|
|
|
594
|
-
在 Modern.js 3.0 中，我们基于 [Storybook Rsbuild](https://github.com/
|
|
594
|
+
在 Modern.js 3.0 中，我们基于 [Storybook Rsbuild](https://github.com/rstackjs/storybook-rsbuild) 实现了使用 Storybook 构建 Modern.js 应用。
|
|
595
595
|
|
|
596
596
|
通过 Storybook Addon，我们将 Modern.js 配置转换合并为 Rsbuild 配置，并通过 Storybook Rsbuild 驱动构建，让 Storybook 调试与开发命令保持配置对齐。
|
|
597
597
|
|
|
@@ -21,7 +21,7 @@ export default {
|
|
|
21
21
|
|
|
22
22
|
### 选项
|
|
23
23
|
|
|
24
|
-
`experiments.sourceBuild` 底层基于 [@rsbuild/plugin-source-build](https://github.com/
|
|
24
|
+
`experiments.sourceBuild` 底层基于 [@rsbuild/plugin-source-build](https://github.com/rstackjs/rsbuild-plugin-source-build?tab=readme-ov-file#options) 实现，你可以传入插件选项，比如：
|
|
25
25
|
|
|
26
26
|
```ts
|
|
27
27
|
export default {
|
|
@@ -30,7 +30,7 @@ type DefaultParameters = {
|
|
|
30
30
|
};
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
-
定义 HTML 模板中的参数，对应 [html-rspack-plugin](https://github.com/
|
|
33
|
+
定义 HTML 模板中的参数，对应 [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) 的 `templateParameters` 配置项。
|
|
34
34
|
|
|
35
35
|
import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
|
|
36
36
|
|
|
@@ -70,4 +70,4 @@ error [Syntax Checker] Find some syntax errors after production build:
|
|
|
70
70
|
|
|
71
71
|
### 选项
|
|
72
72
|
|
|
73
|
-
`security.checkSyntax` 底层基于 `@rsbuild/plugin-check-syntax` 实现，具体选项可参考 [@rsbuild/plugin-check-syntax](https://github.com/
|
|
73
|
+
`security.checkSyntax` 底层基于 `@rsbuild/plugin-check-syntax` 实现，具体选项可参考 [@rsbuild/plugin-check-syntax](https://github.com/rstackjs/rsbuild-plugin-check-syntax)。
|
|
@@ -38,7 +38,7 @@ const defaultOptions = {
|
|
|
38
38
|
SSR 应用请勿启用 `minify.removeComments` 配置项，否则会导致 SSR 渲染失败。
|
|
39
39
|
:::
|
|
40
40
|
|
|
41
|
-
通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/
|
|
41
|
+
通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) 的配置项。
|
|
42
42
|
|
|
43
43
|
import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
|
|
44
44
|
|
|
@@ -12,20 +12,21 @@ import { PackageManagerTabs } from '@theme';
|
|
|
12
12
|
```js
|
|
13
13
|
const defaultOptions = {
|
|
14
14
|
typescript: {
|
|
15
|
+
// set 'readonly' to avoid emitting tsbuildinfo,
|
|
16
|
+
// as the generated tsbuildinfo will break ts-checker-rspack-plugin
|
|
17
|
+
mode: 'readonly',
|
|
18
|
+
// enable build when using project reference
|
|
19
|
+
build: useReference,
|
|
15
20
|
// avoid OOM issue
|
|
16
21
|
memoryLimit: 8192,
|
|
17
22
|
// use tsconfig of user project
|
|
18
23
|
configFile: tsconfigPath,
|
|
19
|
-
//
|
|
20
|
-
|
|
21
|
-
// use typescript of user project
|
|
22
|
-
typescriptPath: require.resolve('typescript'),
|
|
24
|
+
// resolve the default TypeScript package from user project
|
|
25
|
+
resolveRoot: rootPath,
|
|
23
26
|
},
|
|
24
27
|
issue: {
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
{ file: '**/node_modules/**/*' },
|
|
28
|
-
],
|
|
28
|
+
// ignore type errors from node_modules
|
|
29
|
+
exclude: [({ file = '' }) => /[\\/]node_modules[\\/]/.test(file)],
|
|
29
30
|
},
|
|
30
31
|
logger: {
|
|
31
32
|
log() {
|
|
@@ -33,7 +34,11 @@ const defaultOptions = {
|
|
|
33
34
|
// we only want to display error messages
|
|
34
35
|
},
|
|
35
36
|
error(message: string) {
|
|
36
|
-
console.error(
|
|
37
|
+
console.error(
|
|
38
|
+
message
|
|
39
|
+
.replace(/ERROR/g, 'Type Error')
|
|
40
|
+
.replace(/WARNING/g, 'Type Warning'),
|
|
41
|
+
);
|
|
37
42
|
},
|
|
38
43
|
},
|
|
39
44
|
},
|
|
@@ -43,6 +48,8 @@ const defaultOptions = {
|
|
|
43
48
|
|
|
44
49
|
## 示例
|
|
45
50
|
|
|
51
|
+
### Object 类型
|
|
52
|
+
|
|
46
53
|
当 `tsChecker` 的值为 Object 类型时，会与默认配置进行深层合并。
|
|
47
54
|
|
|
48
55
|
```ts
|
|
@@ -57,17 +64,34 @@ export default {
|
|
|
57
64
|
};
|
|
58
65
|
```
|
|
59
66
|
|
|
67
|
+
### Function 类型
|
|
68
|
+
|
|
69
|
+
当 `tsChecker` 的值为 Function 类型时，默认配置会作为第一个参数传入。你可以直接修改配置对象，也可以返回一个对象作为最终配置。
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
export default {
|
|
73
|
+
tools: {
|
|
74
|
+
tsChecker(options) {
|
|
75
|
+
options.async = false;
|
|
76
|
+
return options;
|
|
77
|
+
},
|
|
78
|
+
},
|
|
79
|
+
};
|
|
80
|
+
```
|
|
81
|
+
|
|
60
82
|
> 请参考 [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) 了解更多用法。
|
|
61
83
|
|
|
62
84
|
## TypeScript Go 支持
|
|
63
85
|
|
|
64
86
|
`tools.tsChecker` 支持开启 [TypeScript Go](https://github.com/microsoft/typescript-go) 进行类型检查。该能力由 [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check) 底层集成的 [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin) 提供，目前仍处于实验阶段，可以将类型检查耗时减少约 5-10 倍。
|
|
65
87
|
|
|
66
|
-
|
|
88
|
+
安装 TypeScript 7.0 RC 后，TypeScript Go 会自动开启：
|
|
67
89
|
|
|
68
|
-
<PackageManagerTabs command="install @
|
|
90
|
+
<PackageManagerTabs command="install typescript@rc -D" />
|
|
69
91
|
|
|
70
|
-
|
|
92
|
+
你也可以安装 `@typescript/native-preview`，并将 `typescript.tsgo` 设置为 `true`：
|
|
93
|
+
|
|
94
|
+
<PackageManagerTabs command="install @typescript/native-preview -D" />
|
|
71
95
|
|
|
72
96
|
```ts
|
|
73
97
|
export default {
|
|
@@ -81,6 +105,8 @@ export default {
|
|
|
81
105
|
};
|
|
82
106
|
```
|
|
83
107
|
|
|
84
|
-
开启 `tsgo`
|
|
108
|
+
开启 `tsgo` 后，如果手动设置 `typescript.typescriptPath`，它必须指向 TypeScript 7+ 的 `typescript/package.json` 或 `@typescript/native-preview/package.json` 的绝对路径。
|
|
109
|
+
|
|
110
|
+
> `@typescript/native-preview` 的用法已废弃，仅作为兼容保留。推荐安装 `typescript@rc` 使用 `tsgo`。
|
|
85
111
|
|
|
86
112
|
关于 `tsgo` 模式下生效的配置项和相关限制，请参考 [ts-checker-rspack-plugin - TypeScript Go support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-go-support)。
|
|
@@ -89,4 +89,4 @@ pnpm storybook
|
|
|
89
89
|
|
|
90
90
|
## 示例
|
|
91
91
|
|
|
92
|
-
你可以查看 [示例](https://github.com/
|
|
92
|
+
你可以查看 [示例](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react) 了解 Modern.js 中使用 Storybook 的方式。
|
|
@@ -38,7 +38,7 @@ import { name } from './example.json';
|
|
|
38
38
|
|
|
39
39
|
YAML 是一种数据序列化语言，通常用于编写配置文件。
|
|
40
40
|
|
|
41
|
-
你可以 `modern.config.ts` 中配置 [YAML 插件](https://github.com/
|
|
41
|
+
你可以 `modern.config.ts` 中配置 [YAML 插件](https://github.com/rstackjs/rsbuild-plugin-yaml) 来支持引用 `.yaml` 或 `.yml` 文件，它们会被自动转换为 JSON 格式。
|
|
42
42
|
|
|
43
43
|
```ts
|
|
44
44
|
import { defineConfig } from '@modern-js/app-tools';
|
|
@@ -85,7 +85,7 @@ declare module '*.yml' {
|
|
|
85
85
|
|
|
86
86
|
TOML 是一种语义明显、易于阅读的配置文件格式。
|
|
87
87
|
|
|
88
|
-
你可以 `modern.config.ts` 中配置 [TOML 插件](https://github.com/
|
|
88
|
+
你可以 `modern.config.ts` 中配置 [TOML 插件](https://github.com/rstackjs/rsbuild-plugin-toml) 来支持引用 `.toml` 文件，它会被自动转换为 JSON 格式。
|
|
89
89
|
|
|
90
90
|
```ts
|
|
91
91
|
import { defineConfig } from '@modern-js/app-tools';
|
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
先安装基础依赖：
|
|
10
10
|
|
|
11
|
+
import { Prompt } from '@rspress/core/theme';
|
|
11
12
|
import { PackageManagerTabs } from '@theme';
|
|
12
13
|
|
|
13
14
|
<PackageManagerTabs command="add @rstest/core @modern-js/adapter-rstest -D" />
|
|
@@ -161,3 +162,31 @@ test('Page', () => {
|
|
|
161
162
|
如果你需要测试 `bff` 等 server-side logic，建议直接参考 [Rstest 文档](https://rstest.rs) 中关于 node mode 的说明。
|
|
162
163
|
|
|
163
164
|
Modern.js 主要面向 web app，因此这里重点介绍的是 Web UI 测试，以及更贴近真实运行环境的 browser mode。
|
|
165
|
+
|
|
166
|
+
## 从已有项目迁移
|
|
167
|
+
|
|
168
|
+
如果你的项目已经使用 Jest 或 Vitest，可以参考 Rstest 官方迁移指南：
|
|
169
|
+
|
|
170
|
+
- [从 Jest 迁移到 Rstest](https://rstest.rs/guide/migration/jest)
|
|
171
|
+
- [从 Vitest 迁移到 Rstest](https://rstest.rs/guide/migration/vitest)
|
|
172
|
+
|
|
173
|
+
推荐先安装 `migrate-to-rstest` skill，再复制下面的 Prompt 给编码 Agent；它会在迁移时保留 Modern.js 的 `@modern-js/adapter-rstest` 配置。
|
|
174
|
+
|
|
175
|
+
<Prompt
|
|
176
|
+
title="迁移到 Rstest"
|
|
177
|
+
description="复制这个 Prompt 并发送给你的编码 Agent。"
|
|
178
|
+
prompt={`Migrate this Modern.js project from Jest or Vitest to Rstest.
|
|
179
|
+
|
|
180
|
+
First install and use the migrate-to-rstest skill. If it is not installed, install it with:
|
|
181
|
+
npx skills add rstackjs/agent-skills --skill migrate-to-rstest
|
|
182
|
+
|
|
183
|
+
Follow the migrate-to-rstest skill instructions and the official Rstest migration guides:
|
|
184
|
+
- Jest: https://rstest.rs/guide/migration/jest
|
|
185
|
+
- Vitest: https://rstest.rs/guide/migration/vitest
|
|
186
|
+
|
|
187
|
+
Modern.js-specific requirement:
|
|
188
|
+
- Install and use @modern-js/adapter-rstest together with @rstest/core.
|
|
189
|
+
- Create or update rstest.config.ts to import withModernConfig from @modern-js/adapter-rstest.
|
|
190
|
+
- Reuse the Modern.js app configuration with extends: withModernConfig().
|
|
191
|
+
- Do not replace this with a plain Rstest config unless the project explicitly does not need Modern.js config integration.`}
|
|
192
|
+
/>
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: AI 工具
|
|
3
|
+
sidebar_position: 6
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Modern.js For AI
|
|
7
|
+
|
|
8
|
+
Modern.js 为 AI Agent 提供了一套工具套件，帮助开发者利用 AI 高效完成 Modern.js 应用的功能开发、依赖升级与版本迁移工作。
|
|
9
|
+
|
|
10
|
+
## llms.txt
|
|
11
|
+
|
|
12
|
+
Modern.js 文档遵循 [llms.txt 规范](https://llmstxt.org/)，由 [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms) 自动生成，可通过 `/llms.txt` 或 `/llms-full.txt` 供 AI 工具检索：
|
|
13
|
+
|
|
14
|
+
- 索引：[`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
|
|
15
|
+
- 全文：`https://modernjs.dev/llms-full.txt`（体积较大，按需取片段）
|
|
16
|
+
|
|
17
|
+
大部分「这个 API / 配置是什么」类问题，靠 llms.txt 即可解决。让你的 Agent 按需检索它即可，不必把文档复制进项目。
|
|
18
|
+
|
|
19
|
+
## Skills
|
|
20
|
+
|
|
21
|
+
Skills 是按需触发的 AI 辅助能力，遵循 [Agent Skills 开放标准](https://github.com/vercel-labs/skills)。用户向 Skills：
|
|
22
|
+
|
|
23
|
+
| Skill | 标识 | 说明 |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| 升级到 v3 | `modernjs-migrate-to-v3` | v2 应用迁移到 v3：安全改写 + 复杂项人工清单 + 迁移报告 |
|
|
26
|
+
| 启用特性 | `modernjs-feature-enable` | 为 v3 应用启用 BFF / SSG / styled-components，并脚手架化 Tailwind CSS / 自定义 Web Server |
|
|
27
|
+
|
|
28
|
+
> Skills 默认不强装、不隐式安装，由你显式安装。RSC、微前端等属于配置或架构决策，不是 `modernjs-feature-enable` 的一键启用项。
|
|
29
|
+
|
|
30
|
+
## 安装 Skills
|
|
31
|
+
|
|
32
|
+
Modern.js 的用户向 Skill 就放在仓库根 `skills/` 目录，遵循 [Agent Skills 开放标准](https://github.com/vercel-labs/skills)。推荐用标准的 `skills` CLI 直接从 GitHub 安装：
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
# 列出可安装的 Skills
|
|
36
|
+
npx skills add web-infra-dev/modern.js --list
|
|
37
|
+
|
|
38
|
+
# 安装单个 Skill 到你的 Agent 目录（--agent 可选 claude-code / codex / cursor 等）
|
|
39
|
+
npx skills add web-infra-dev/modern.js --skill modernjs-migrate-to-v3 --agent codex -y
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
它会把整个 Skill 目录（`SKILL.md` + `scripts/` + `references/`）安装到对应 Agent 目录，随后即可在该 Agent 里触发。
|
|
43
|
+
|
|
44
|
+
> 需锁定到某个版本时，在仓库后加 `#<ref>`（ref 可为 tag / 分支 / commit），即安装该版本上的 Skill（把 `<tag>` 换成含本 Skill 的发布 tag）：
|
|
45
|
+
>
|
|
46
|
+
> ```bash
|
|
47
|
+
> npx skills add web-infra-dev/modern.js#<tag> --skill modernjs-migrate-to-v3 --agent codex -y
|
|
48
|
+
> ```
|
|
@@ -314,7 +314,7 @@ export default {
|
|
|
314
314
|
|
|
315
315
|
### tools.pug
|
|
316
316
|
|
|
317
|
-
**变更内容**：该配置已废弃，使用 Rsbuild 的 [Pug 插件](https://github.com/
|
|
317
|
+
**变更内容**：该配置已废弃，使用 Rsbuild 的 [Pug 插件](https://github.com/rstackjs/rsbuild-plugin-pug) 来启用支持。
|
|
318
318
|
|
|
319
319
|
**迁移示例**：
|
|
320
320
|
|
|
@@ -131,21 +131,21 @@ Rsbuild 是 Modern.js 底层的构建工具，通过添加 Rsbuild 插件可修
|
|
|
131
131
|
| [React 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-react) | 提供对 React 的支持 | - |
|
|
132
132
|
| [SVGR 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-svgr) | 支持将 SVG 图片转换为一个 React 组件 | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export) |
|
|
133
133
|
| [Assets Retry 插件](https://github.com/rstackjs/rsbuild-plugin-assets-retry) | 用于在静态资源加载失败时自动发起重试请求 | [output.assetsRetry](/configure/app/output/assets-retry.html) |
|
|
134
|
-
| [Type Check 插件](https://github.com/
|
|
135
|
-
| [Source Build 插件](https://github.com/
|
|
136
|
-
| [Check Syntax 插件](https://github.com/
|
|
137
|
-
| [CSS Minimizer 插件](https://github.com/
|
|
138
|
-
| [Rem 插件](https://github.com/
|
|
134
|
+
| [Type Check 插件](https://github.com/rstackjs/rsbuild-plugin-type-check) | 用于在单独的进程中运行 TypeScript 类型检查 | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
|
|
135
|
+
| [Source Build 插件](https://github.com/rstackjs/rsbuild-plugin-source-build) | 用于 monorepo 场景，支持引用其他子目录的源代码，并完成构建和热更新 | [experiments.sourceBuild](/configure/app/experiments/source-build.html) |
|
|
136
|
+
| [Check Syntax 插件](https://github.com/rstackjs/rsbuild-plugin-check-syntax) | 用于分析产物的语法兼容性，判断是否存在导致兼容性问题的高级语法 | [security.checkSyntax](/configure/app/security/check-syntax.html) |
|
|
137
|
+
| [CSS Minimizer 插件](https://github.com/rstackjs/rsbuild-plugin-css-minimizer) | 用于自定义 CSS 压缩工具，切换到 [cssnano](https://cssnano.co/) 或其他工具进行 CSS 压缩 | [tools.minifyCss](/configure/app/tools/minify-css.html) |
|
|
138
|
+
| [Rem 插件](https://github.com/rstackjs/rsbuild-plugin-rem) | 用于实现移动端页面的 rem 自适应布局 | [output.convertToRem](/configure/app/output/convert-to-rem.html) |
|
|
139
139
|
|
|
140
140
|
#### 未内置的插件
|
|
141
141
|
|
|
142
142
|
以下是未在 Modern.js 中内置的 Rsbuild 官方插件：
|
|
143
143
|
|
|
144
|
-
- [Image Compress 插件](https://github.com/
|
|
144
|
+
- [Image Compress 插件](https://github.com/rstackjs/rsbuild-plugin-image-compress)：将项目中用到的图片资源进行压缩处理。
|
|
145
145
|
- [Stylus 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-stylus)：使用 Stylus 作为 CSS 预处理器。
|
|
146
|
-
- [UMD 插件](https://github.com/
|
|
147
|
-
- [YAML 插件](https://github.com/
|
|
148
|
-
- [TOML 插件](https://github.com/
|
|
146
|
+
- [UMD 插件](https://github.com/rstackjs/rsbuild-plugin-umd)：用于构建 UMD 格式的产物。
|
|
147
|
+
- [YAML 插件](https://github.com/rstackjs/rsbuild-plugin-yaml)：用于引用 YAML 文件，并将其转换为 JavaScript 对象。
|
|
148
|
+
- [TOML 插件](https://github.com/rstackjs/rsbuild-plugin-toml)：用于引用 TOML 文件，并将其转换为 JavaScript 对象。
|
|
149
149
|
|
|
150
150
|
import OtherPlugins from '@site-docs/components/other-plugins.mdx';
|
|
151
151
|
|
package/package.json
CHANGED
|
@@ -16,14 +16,14 @@
|
|
|
16
16
|
"modern",
|
|
17
17
|
"modern.js"
|
|
18
18
|
],
|
|
19
|
-
"version": "3.
|
|
19
|
+
"version": "3.5.0",
|
|
20
20
|
"publishConfig": {
|
|
21
21
|
"registry": "https://registry.npmjs.org/",
|
|
22
22
|
"access": "public"
|
|
23
23
|
},
|
|
24
24
|
"dependencies": {
|
|
25
25
|
"mermaid": "^11.15.0",
|
|
26
|
-
"@modern-js/sandpack-react": "3.
|
|
26
|
+
"@modern-js/sandpack-react": "3.5.0"
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
29
|
"rsbuild-plugin-open-graph": "1.1.3",
|