@modern-js/main-doc 2.52.0 → 2.54.0
Sign up to get free protection for your applications and to get access to all the features.
- package/docs/en/configure/app/server/ssr.mdx +2 -0
- package/docs/en/guides/advanced-features/bff/index.mdx +1 -1
- package/docs/en/guides/advanced-features/code-split.mdx +4 -4
- package/docs/en/guides/advanced-features/ssr/index.mdx +1 -0
- package/docs/en/guides/basic-features/routes.mdx +3 -3
- package/docs/en/guides/get-started/introduction.mdx +1 -1
- package/docs/en/guides/get-started/tech-stack.mdx +0 -6
- package/docs/en/guides/topic-detail/framework-plugin/plugin-api.mdx +1 -1
- package/docs/en/guides/topic-detail/generator/create/config.mdx +0 -6
- package/docs/en/guides/topic-detail/generator/create/option.md +0 -5
- package/docs/en/guides/topic-detail/generator/create/use.mdx +1 -10
- package/docs/en/guides/topic-detail/generator/new/config.md +0 -29
- package/docs/en/guides/topic-detail/generator/new/use.md +1 -21
- package/docs/zh/configure/app/server/ssr.mdx +2 -0
- package/docs/zh/guides/advanced-features/bff/index.mdx +2 -2
- package/docs/zh/guides/advanced-features/code-split.mdx +5 -5
- package/docs/zh/guides/advanced-features/rspack-start.mdx +1 -1
- package/docs/zh/guides/advanced-features/ssr/index.mdx +2 -1
- package/docs/zh/guides/advanced-features/ssr/usage.mdx +2 -2
- package/docs/zh/guides/basic-features/data/data-fetch.mdx +2 -2
- package/docs/zh/guides/basic-features/data/data-write.mdx +1 -2
- package/docs/zh/guides/basic-features/mock.mdx +1 -1
- package/docs/zh/guides/basic-features/routes.mdx +6 -6
- package/docs/zh/guides/get-started/introduction.mdx +1 -1
- package/docs/zh/guides/get-started/tech-stack.mdx +0 -6
- package/docs/zh/guides/topic-detail/framework-plugin/plugin-api.mdx +1 -1
- package/docs/zh/guides/topic-detail/generator/create/config.mdx +0 -6
- package/docs/zh/guides/topic-detail/generator/create/option.md +0 -5
- package/docs/zh/guides/topic-detail/generator/create/use.mdx +1 -10
- package/docs/zh/guides/topic-detail/generator/new/config.md +0 -31
- package/docs/zh/guides/topic-detail/generator/new/use.md +1 -21
- package/package.json +5 -5
- package/docs/en/apis/app/runtime/testing/_category_.json +0 -4
- package/docs/en/apis/app/runtime/testing/act.mdx +0 -35
- package/docs/en/apis/app/runtime/testing/cleanup.mdx +0 -40
- package/docs/en/apis/app/runtime/testing/render.mdx +0 -71
- package/docs/en/apis/app/runtime/testing/renderApp.mdx +0 -34
- package/docs/en/configure/app/testing/_category_.json +0 -4
- package/docs/en/configure/app/testing/transformer.mdx +0 -17
- package/docs/en/configure/app/tools/jest.mdx +0 -40
- package/docs/en/guides/advanced-features/testing.mdx +0 -47
- package/docs/en/guides/topic-detail/changesets/_category_.json +0 -4
- package/docs/en/guides/topic-detail/changesets/add.mdx +0 -125
- package/docs/en/guides/topic-detail/changesets/changelog.mdx +0 -238
- package/docs/en/guides/topic-detail/changesets/commit.mdx +0 -269
- package/docs/en/guides/topic-detail/changesets/config.mdx +0 -147
- package/docs/en/guides/topic-detail/changesets/github.mdx +0 -175
- package/docs/en/guides/topic-detail/changesets/introduce.mdx +0 -56
- package/docs/en/guides/topic-detail/changesets/release-note.mdx +0 -274
- package/docs/en/guides/topic-detail/changesets/release-pre.mdx +0 -49
- package/docs/en/guides/topic-detail/changesets/release.mdx +0 -229
- package/docs/en/guides/topic-detail/model/test-model.mdx +0 -45
- package/docs/zh/apis/app/runtime/testing/_category_.json +0 -4
- package/docs/zh/apis/app/runtime/testing/act.mdx +0 -35
- package/docs/zh/apis/app/runtime/testing/cleanup.mdx +0 -40
- package/docs/zh/apis/app/runtime/testing/render.mdx +0 -71
- package/docs/zh/apis/app/runtime/testing/renderApp.mdx +0 -32
- package/docs/zh/configure/app/testing/_category_.json +0 -4
- package/docs/zh/configure/app/testing/transformer.mdx +0 -19
- package/docs/zh/configure/app/tools/jest.mdx +0 -40
- package/docs/zh/guides/advanced-features/testing.mdx +0 -47
- package/docs/zh/guides/topic-detail/changesets/_category_.json +0 -4
- package/docs/zh/guides/topic-detail/changesets/add.mdx +0 -126
- package/docs/zh/guides/topic-detail/changesets/changelog.mdx +0 -238
- package/docs/zh/guides/topic-detail/changesets/commit.mdx +0 -269
- package/docs/zh/guides/topic-detail/changesets/config.mdx +0 -147
- package/docs/zh/guides/topic-detail/changesets/github.mdx +0 -175
- package/docs/zh/guides/topic-detail/changesets/introduce.mdx +0 -56
- package/docs/zh/guides/topic-detail/changesets/release-note.mdx +0 -274
- package/docs/zh/guides/topic-detail/changesets/release-pre.mdx +0 -50
- package/docs/zh/guides/topic-detail/changesets/release.mdx +0 -231
- package/docs/zh/guides/topic-detail/model/test-model.mdx +0 -45
- package/docs/zh/guides/topic-detail/monorepo/_category_.json +0 -4
- package/docs/zh/guides/topic-detail/monorepo/create-sub-project.mdx +0 -53
- package/docs/zh/guides/topic-detail/monorepo/intro.mdx +0 -14
- package/docs/zh/guides/topic-detail/monorepo/publish.mdx +0 -69
- package/docs/zh/guides/topic-detail/monorepo/sub-project-interface.mdx +0 -143
@@ -32,6 +32,8 @@ When the value type is `Object`, the following properties can be configured:
|
|
32
32
|
However, if developers want to reduce one rendering when there is no use of the useLoader API in your project, you can set the configuration `disablePrerender=true`.
|
33
33
|
- `unsafeHeaders`: `string[] = []`, For safety reasons, Modern.js does not add excessive content to SSR_DATA. Developers can use this configuration to specify the headers that need to be injected.
|
34
34
|
- `scriptLoading`: `'defer' | 'blocking' | 'module' | 'async'`, The configuration is the same as [html.scriptLoading](/configure/app/html/script-loading), supporting SSR injected script set to `async` loading. The priority is `ssr.scriptLoading` > `html.scriptLoading`.
|
35
|
+
- `loaderFailureMode`: `'clientRender' | 'errorBoundary'`, The default configuration is `'errorBoundary'`, when an error occurs in [data loader](/en/guides/basic-features/data/data-fetch.html#data-loader-recommended),
|
36
|
+
it will default to rendering the [`Error`](/en/guides/basic-features/routes.html#errorboundary) component of the route. When configured as `'clientRender'`, if a loader throws an error, it switch to client-side rendering,you can use it with [Client Loader](/en/guides/basic-features/data/data-fetch.html#client-loader).
|
35
37
|
|
36
38
|
```ts title="modern.config.ts"
|
37
39
|
export default defineConfig({
|
@@ -4,7 +4,7 @@ title: BFF
|
|
4
4
|
|
5
5
|
# BFF
|
6
6
|
|
7
|
-
|
7
|
+
BFF (Backends for Frontends) is an architectural pattern primarily used to address issues of data aggregation in front-end and back-end collaboration. Under the BFF architecture, front-end applications do not communicate directly with backend services. Instead, they interact with backend services through a dedicated BFF middleware layer, custom-made for the front end.
|
8
8
|
|
9
9
|
The main problems it to solve include:
|
10
10
|
|
@@ -10,11 +10,11 @@ Code splitting is a common way to optimize frontend resource loading. This artic
|
|
10
10
|
When using Modern.js [Conventional routing](/guides/basic-features/routes#conventional-routing). By default, code splitting is done according to the routing component, so you don't need to do it yourself.
|
11
11
|
:::
|
12
12
|
|
13
|
-
- `import`
|
13
|
+
- dynamic `import`
|
14
14
|
- `React.lazy`
|
15
15
|
- `loadable`
|
16
16
|
|
17
|
-
## import
|
17
|
+
## Dynamic import
|
18
18
|
|
19
19
|
use dynamic `import()`, the JS modules pass to this API will be bundled as a separate JS file, for example:
|
20
20
|
|
@@ -34,7 +34,7 @@ The officially way provides by React to split component code.
|
|
34
34
|
For projects that use Traditional SSR(renderToString), `React.lazy` is not supported. Please use the Loadable API instead.
|
35
35
|
:::
|
36
36
|
|
37
|
-
```
|
37
|
+
```tsx
|
38
38
|
import React, { Suspense } from 'react';
|
39
39
|
|
40
40
|
const OtherComponent = React.lazy(() => import('./OtherComponent'));
|
@@ -60,7 +60,7 @@ For details, see [React lazy](https://react.dev/reference/react/lazy).
|
|
60
60
|
|
61
61
|
In Modern.js, you can use the Loadable API, which is exported from `@modern-js/runtime/loadable`. Here's an example:
|
62
62
|
|
63
|
-
```
|
63
|
+
```tsx
|
64
64
|
import loadable from '@modern-js/runtime/loadable';
|
65
65
|
|
66
66
|
const OtherComponent = loadable(() => import('./OtherComponent'));
|
@@ -15,6 +15,7 @@ If you have the following scenarios, developers can consider using SSR to render
|
|
15
15
|
3. Websites with higher SEO requirements, such as corporate websites, blogs, etc.
|
16
16
|
|
17
17
|
In Modern.js, SSR is also out-of-the-box. Developers do not need to write complex server-side logic for SSR, nor do they need to worry about the operation and maintenance of SSR, or create separate services.
|
18
|
+
|
18
19
|
In addition to the out-of-the-box SSR service, to ensure the developer's development experience, we also have:
|
19
20
|
|
20
21
|
- A complete SSR downgrade strategy to ensure that the page can run safely.
|
@@ -226,7 +226,7 @@ For example, the following directory structure:
|
|
226
226
|
└── page.tsx
|
227
227
|
```
|
228
228
|
|
229
|
-
When accessing any path that does not match(For example `/blog/a`), the `routes/$.tsx` component will be rendered, because there is `layout.tsx` here, the rendered UI is as follows.
|
229
|
+
When accessing any path that does not match(For example `/blog/a`), the `routes/blog/$.tsx` component will be rendered, because there is `layout.tsx` here, the rendered UI is as follows.
|
230
230
|
|
231
231
|
```tsx
|
232
232
|
<RootLayout>
|
@@ -455,8 +455,8 @@ export const init = (context: RuntimeContext) => {
|
|
455
455
|
import { useRuntimeContext } from '@modern-js/runtime';
|
456
456
|
|
457
457
|
export default () => {
|
458
|
-
const
|
459
|
-
const { message } = context.
|
458
|
+
const context = useRuntimeContext();
|
459
|
+
const { message } = context.initialData;
|
460
460
|
|
461
461
|
return <div>{message}</div>;
|
462
462
|
};
|
@@ -54,7 +54,7 @@ It mainly includes the following features:
|
|
54
54
|
- 🪜 **Progressive**: Create projects with the most streamlined templates, gradually enable plugin features through the generator, and customize solutions.
|
55
55
|
- 🏠 **Integration**: Development and production environment web server are unique, CSR and SSR are isomorphic development, and API service calls are functions as interfaces.
|
56
56
|
- 📦 **Out Of The Box**: Default TS support, built-in build, ESLint, debugging tools, fully functional and testable.
|
57
|
-
- 🌏 **Ecology**: Self-developed state management, micro-frontend, module packaging,
|
57
|
+
- 🌏 **Ecology**: Self-developed state management, micro-frontend, module packaging, and other peripheral needs.
|
58
58
|
- 🕸 **Routing Modes**: Includes self-controlled routing, file-convention-based routing (nested routing), etc.
|
59
59
|
|
60
60
|
## Comparison with Others
|
@@ -83,12 +83,6 @@ Modern.js supports the use of [styled-components](https://styled-components.com/
|
|
83
83
|
|
84
84
|
If you need to use other CSS-in-JS solutions, you can integrate them into your project on your own.
|
85
85
|
|
86
|
-
## Testing Framework
|
87
|
-
|
88
|
-
Modern.js supports the use of [Jest](https://jestjs.io/) for unit testing or integration testing. This feature is optional. Please refer to ["Using Jest"](/en/guides/advanced-features/testing) to enable it.
|
89
|
-
|
90
|
-
If you need to use [Vitest](https://vitest.dev/) or other testing frameworks, you can integrate them into your project on your own.
|
91
|
-
|
92
86
|
## UI Components
|
93
87
|
|
94
88
|
Modern.js can be used with any React UI component library from the community, such as [MUI](https://mui.com/), [Ant Design](https://ant.design/), [Arco Design](https://github.com/arco-design/arco-design), [Semi Design](https://semi.design/), [Radix UI](https://www.radix-ui.com/), and more.
|
@@ -105,7 +105,7 @@ interface IAppContext {
|
|
105
105
|
/** Information for server routes */
|
106
106
|
serverRoutes: ServerRoute[];
|
107
107
|
/** Tools type of the current project */
|
108
|
-
toolsType?: 'app-tools' | 'module-tools'
|
108
|
+
toolsType?: 'app-tools' | 'module-tools';
|
109
109
|
/** Type of the bundler being used */
|
110
110
|
bundlerType?: 'webpack' | 'rspack' | 'esbuild';
|
111
111
|
}
|
@@ -22,8 +22,6 @@ Options:
|
|
22
22
|
|
23
23
|
- Doc Site -- doc
|
24
24
|
|
25
|
-
- Monorepo -- monorepo
|
26
|
-
|
27
25
|
### scenes
|
28
26
|
|
29
27
|
Question: Please select the project scenario.
|
@@ -69,7 +67,3 @@ The value of the `name` field in the `package.json` file of the Npm module, whic
|
|
69
67
|
## Modern Doc
|
70
68
|
|
71
69
|
<PackageManager />
|
72
|
-
|
73
|
-
## Monorepo
|
74
|
-
|
75
|
-
<PackageManager />
|
@@ -20,7 +20,6 @@ Options:
|
|
20
20
|
-d,--debug using debug mode to log something (default: false)
|
21
21
|
--mwa create mwa application using default config (default: false)
|
22
22
|
--module create module application using default config (default: false)
|
23
|
-
--monorepo create monorepo application using default config (default: false)
|
24
23
|
--generator <generator> run custom generator
|
25
24
|
-p, --plugin <plugin> use generator plugin to create new solution or customize Modern.js solution (default: [])
|
26
25
|
--dist-tag <distTag> use specified tag version for it\'s generator (default: "")
|
@@ -89,10 +88,6 @@ Quickly create a Web App project.
|
|
89
88
|
|
90
89
|
Quickly create a Npm Module project.
|
91
90
|
|
92
|
-
## --monorepo
|
93
|
-
|
94
|
-
Quickly create a Monorepo project.
|
95
|
-
|
96
91
|
## -p, --plugin \<plugin>
|
97
92
|
|
98
93
|
Specify a generator plugin.
|
@@ -4,7 +4,7 @@ sidebar_position: 1
|
|
4
4
|
|
5
5
|
# Usage
|
6
6
|
|
7
|
-
Modern.js provides `@modern-js/create` tool for creating project templates provided by Modern.js, including [Web App](https://modernjs.dev/), [Npm Module](https://modernjs.dev/module-tools)
|
7
|
+
Modern.js provides `@modern-js/create` tool for creating project templates provided by Modern.js, including [Web App](https://modernjs.dev/), [Npm Module](https://modernjs.dev/module-tools).
|
8
8
|
|
9
9
|
The following will introduce how to use `@modern-js/create`.
|
10
10
|
|
@@ -47,12 +47,3 @@ npx @modern-js/create@latest npm-module
|
|
47
47
|
? Please select the programming language: TS
|
48
48
|
? Please select the package manager: pnpm
|
49
49
|
```
|
50
|
-
|
51
|
-
### Create Monorepo Project
|
52
|
-
|
53
|
-
```bash
|
54
|
-
npx @modern-js/create@latest monorepo
|
55
|
-
? Please select the type of project you want to create: Monorepo
|
56
|
-
? Please select the package manager: pnpm
|
57
|
-
```
|
58
|
-
|
@@ -117,32 +117,3 @@ Options:
|
|
117
117
|
- Enable Storybook -- storybook
|
118
118
|
|
119
119
|
- Enable Runtime API -- runtime_api
|
120
|
-
|
121
|
-
## Monorepo
|
122
|
-
|
123
|
-
### sub_solution
|
124
|
-
|
125
|
-
Question: Please select the type of project you want to create.
|
126
|
-
|
127
|
-
Options:
|
128
|
-
|
129
|
-
- Web App -- mwa
|
130
|
-
- Npm Module -- module
|
131
|
-
|
132
|
-
### packageName
|
133
|
-
|
134
|
-
Question: Please fill in the project name
|
135
|
-
|
136
|
-
:::info
|
137
|
-
The value of the `name` field in the `package.json` file of the sub-project, which is a string type.
|
138
|
-
|
139
|
-
:::
|
140
|
-
|
141
|
-
### packagePath
|
142
|
-
|
143
|
-
Question: Please fill in the sub-project directory name
|
144
|
-
|
145
|
-
:::info
|
146
|
-
The name of the subdirectory in the `apps` or `packages` directory on which the sub-project is based, which is a string type.
|
147
|
-
|
148
|
-
:::
|
@@ -4,7 +4,7 @@ sidebar_position: 1
|
|
4
4
|
|
5
5
|
# Usage
|
6
6
|
|
7
|
-
In Web App, Npm Module
|
7
|
+
In Web App, Npm Module projects, we provide the `new` command to create project elements, enable features and create sub-project.
|
8
8
|
|
9
9
|
## Web App
|
10
10
|
|
@@ -73,23 +73,3 @@ npm run new
|
|
73
73
|
```
|
74
74
|
|
75
75
|
After running, Storybook plugin dependencies will be installed in the project, and the `storybook` command will be added. A `stories` directory will be created for Storybook module development, along with prompt information for registering Storybook plugins.
|
76
|
-
|
77
|
-
## Monorepo
|
78
|
-
|
79
|
-
Monorepo projects use the `new` command provided by `@modern-js/monorepo-tools`.
|
80
|
-
|
81
|
-
The `new` command provides the ability to create sub-project.
|
82
|
-
|
83
|
-
For example:
|
84
|
-
|
85
|
-
Create Web App Sub-project:
|
86
|
-
|
87
|
-
```bash
|
88
|
-
? Please select the type of project you want to create: Web App
|
89
|
-
? Please fill in the sub-project name: web_app
|
90
|
-
? Please fill in the sub-project directory name: web_app
|
91
|
-
? Please select the programming language: TS
|
92
|
-
? Please select the bundler: webpack
|
93
|
-
```
|
94
|
-
|
95
|
-
After running, a sub-project named `web_app` will be created in the `apps` directory of the project. In the sub-project directory, you can still run the `new` command to create project elements and enable features.
|
@@ -32,6 +32,8 @@ export default defineConfig({
|
|
32
32
|
开发者在保证项目中没有使用 useLoader Api 情况下, 可通过配置 `disablePrerender=true`来减少一次渲染。
|
33
33
|
- `unsafeHeaders`: `string[] = []`, 为了安全考虑,Modern.js 不会往 SSR_DATA 添加过多的内容。开发者可以通过该配置,对需要注入的 headers 进行配置。
|
34
34
|
- `scriptLoading`: `'defer' | 'blocking' | 'module' | 'async'`, 配置同 [html.scriptLoading](/configure/app/html/script-loading),支持 ssr 注入的 script 设置为 async 加载方式。优先级为 `ssr.scriptLoading` > `html.scriptLoading`
|
35
|
+
- `loaderFailureMode`: `'clientRender' | 'errorBoundary'`, 默认配置为 `'errorBoundary'`,当 [data loader](/guides/basic-features/data/data-fetch.html#data-loader推荐) 中出错时,默认会渲染路由 [`Error`](/guides/basic-features/routes.html#错误处理) 组件,
|
36
|
+
配置为 `'clientRender'` 时,有一个 data loader 抛错,就降级到客户端渲染,可以与 [Client Loader](/guides/basic-features/data/data-fetch.html#client-loader) 配合使用。
|
35
37
|
|
36
38
|
```ts title="modern.config.ts"
|
37
39
|
export default defineConfig({
|
@@ -3,9 +3,9 @@ title: BFF
|
|
3
3
|
---
|
4
4
|
# BFF
|
5
5
|
|
6
|
-
|
6
|
+
BFF(Backends for Frontends)是一种架构模式,主要用于解决前后端协作中的数据聚合问题。在 BFF 架构下,前端应用程序不直接与后端服务通信,而是通过一个专门为前端定制的BFF中间层与后端服务交互。
|
7
7
|
|
8
|
-
|
8
|
+
它的适用场景包括:
|
9
9
|
|
10
10
|
- 根据自身业务需求,对更底层 API 的聚合、映射、裁剪、代理。
|
11
11
|
- 对一些特定场景的数据进行缓存,提高性能,进而提升用户体验。
|
@@ -4,17 +4,17 @@ sidebar_position: 3
|
|
4
4
|
|
5
5
|
# 代码分割
|
6
6
|
|
7
|
-
|
7
|
+
代码分割(code splitting)是优化前端资源加载的一种常用手段,本文将介绍 Modern.js 支持的三种代码分割方式:
|
8
8
|
|
9
9
|
:::info
|
10
10
|
使用 Modern.js [约定式路由](/guides/basic-features/routes#约定式路由)时,默认会根据路由组件做代码分割,无需自行进行代码分割。
|
11
11
|
:::
|
12
12
|
|
13
|
-
- `import`
|
13
|
+
- 动态 `import`
|
14
14
|
- `React.lazy`
|
15
15
|
- `loadable`
|
16
16
|
|
17
|
-
## import
|
17
|
+
## 动态 import
|
18
18
|
|
19
19
|
使用动态 `import()` 语法,传入的 JS 模块将会被被打包到单独的 JS 文件中。例如:
|
20
20
|
|
@@ -34,7 +34,7 @@ React 官方提供的组件代码分割的方式。
|
|
34
34
|
对于使用传统 SSR(字符串渲染)的项目,不支持 `React.lazy`,请使用 Loadable API。
|
35
35
|
:::
|
36
36
|
|
37
|
-
```
|
37
|
+
```tsx
|
38
38
|
import React, { Suspense } from 'react';
|
39
39
|
|
40
40
|
const OtherComponent = React.lazy(() => import('./OtherComponent'));
|
@@ -60,7 +60,7 @@ function MyComponent() {
|
|
60
60
|
|
61
61
|
在 Modern.js 中,可以从 `@modern-js/runtime/loadable` 中导出使用 Loadable API,示例如下:
|
62
62
|
|
63
|
-
```
|
63
|
+
```tsx
|
64
64
|
import loadable from '@modern-js/runtime/loadable';
|
65
65
|
|
66
66
|
const OtherComponent = loadable(() => import('./OtherComponent'));
|
@@ -137,7 +137,7 @@ export default defineConfig<'rspack'>({
|
|
137
137
|
|
138
138
|
:::tip Nightly 版本介绍
|
139
139
|
每天,Rspack 会自动构建基于最新代码的 nightly 版本,用于测试和及早发现错误。
|
140
|
-
|
140
|
+
通常情况下,这些版本是可用的。如果发现问题,我们会及时进行修复。但如果 Rspack 有一些 breaking change、需要 Modern.js 同步修改代码,那么我们建议等待下一个 Modern.js 版本再进行更新。
|
141
141
|
:::
|
142
142
|
|
143
143
|
如果想了解其他包管理工具锁定依赖版本的示例,可以参考:[锁定子依赖](/guides/get-started/upgrade.html#%E9%94%81%E5%AE%9A%E5%AD%90%E4%BE%9D%E8%B5%96)。
|
@@ -1,6 +1,6 @@
|
|
1
1
|
# 服务端渲染
|
2
2
|
|
3
|
-
通过在服务器端将网页的 HTML
|
3
|
+
通过在服务器端将网页的 HTML 内容渲染成完整的网页(Server-Side Rendering,简称 SSR),然后将生成的网页发送到客户端,客户端只需要显示网页即可,不需要再进行额外的渲染。
|
4
4
|
|
5
5
|
它主要的优势在于
|
6
6
|
|
@@ -15,6 +15,7 @@
|
|
15
15
|
3. 对 SEO 要求较高的网站,如企业官网、博客等。
|
16
16
|
|
17
17
|
在 Modern.js 中,SSR 也是开箱即用的。开发者无需为 SSR 编写复杂的服务端逻辑,也无需关心 SSR 的运维,或是创建单独的服务。
|
18
|
+
|
18
19
|
除了开箱即用的 SSR 服务,为了保证开发者的开发体验,我们还具备:
|
19
20
|
|
20
21
|
- 完备的 SSR 降级策略,保证页面能够安全运行。
|
@@ -19,7 +19,7 @@ export default defineConfig({
|
|
19
19
|
|
20
20
|
## SSR 时的数据获取
|
21
21
|
|
22
|
-
Modern.js 中提供了 Data Loader,方便开发者在 SSR、CSR
|
22
|
+
Modern.js 中提供了 Data Loader,方便开发者在 SSR、CSR 下同构地获取数据。每个路由模块,如 `layout.tsx` 和 `page.tsx` 都可以定义自己的 Data Loader:
|
23
23
|
|
24
24
|
```ts title="src/routes/page.data.ts"
|
25
25
|
export const loader = () => {
|
@@ -129,7 +129,7 @@ CSR 中这类问题不易被发觉,因此从 CSR 切换到 SSR 时,如果不
|
|
129
129
|
|
130
130
|
## 收敛服务端数据
|
131
131
|
|
132
|
-
|
132
|
+
为了使浏览器端能够直接使用 SSR 阶段请求的数据,Modern.js 会将渲染过程中收集的数据与状态注入到 HTML 内。但是,CSR 应用常常存在接口数据量大、组件状态未收敛的情况,这时如果直接使用 SSR,渲染得到的 HTML 体积可能会存在过大的问题。此时,SSR 不仅无法为应用带来用户体验上的提升,反而可能起到相反的作用。
|
133
133
|
|
134
134
|
因此,使用 SSR 时,**开发者需要为应用做合理的瘦身**:
|
135
135
|
|
@@ -14,7 +14,7 @@ Modern.js 中提供了开箱即用的数据获取能力,开发者可以通过
|
|
14
14
|
Modern.js 推荐使用约定式路由做路由的管理,通过 Modern.js 的[约定式(嵌套)路由](/guides/basic-features/routes#约定式路由),每个路由组件(`layout.ts` 或 `page.ts`)可以有一个同名的 `data` 文件,该 `data` 文件可以导出一个 `loader` 函数,函数会在组件渲染之前执行,为路由组件提供数据。
|
15
15
|
|
16
16
|
:::info
|
17
|
-
Modern.js v1 支持通过 [useLoader](#useloader(旧版))
|
17
|
+
Modern.js v1 支持通过 [useLoader](#useloader(旧版)) 获取数据,这已经不是我们推荐的用法。除迁移过程外,不推荐两者混用。
|
18
18
|
|
19
19
|
:::
|
20
20
|
|
@@ -379,7 +379,7 @@ export const shouldRevalidate: ShouldRevalidateFunction = ({
|
|
379
379
|
1. 在 SSR 降级时,不希望框架向 SSR 服务发送请求获取数据,希望能直接请求后端服务。
|
380
380
|
2. 在客户端有一些缓存,不希望请求 SSR 服务获取数据。
|
381
381
|
|
382
|
-
这些场景下,我们可以使用 Client Loader
|
382
|
+
这些场景下,我们可以使用 Client Loader。添加 Client Loader 后,会调用 Client Loader 中的代码,而不再像 SSR 服务发送请求:
|
383
383
|
|
384
384
|
1. SSR 降级为 CSR 后,在客户端获取数据时,会执行 Client Loader 代替框架发送请求到 Data Loader(Server) 获取数据。
|
385
385
|
2. SSR 项目进行 SPA 跳转时,获取数据,会执行 Clinet Loader。
|
@@ -83,8 +83,7 @@ Modern.js 中提供 Data Action 主要是为了使 UI 和服务器的状态能
|
|
83
83
|
|
84
84
|

|
85
85
|
|
86
|
-
|
87
|
-
通过 Data Action 修改和同步服务端的状态。
|
86
|
+
如果项目中组件共享的数据主要来自于服务端的状态,则无需在项目引入客户端状态管理库。可以使用 Data Loader 请求数据,通过 [`useRouteLoaderData`](/guides/basic-features/data/data-fetch.md) 在子组件中共享数据,使用 Data Action 修改和同步服务端的状态。
|
88
87
|
|
89
88
|
|
90
89
|
|
@@ -230,7 +230,7 @@ export default () => {
|
|
230
230
|
└── page.tsx
|
231
231
|
```
|
232
232
|
|
233
|
-
当访问任何匹配不到的路径时(如 `/blog/a`),都会渲染 `routes/$.tsx` 组件,因为这里有 `layout.tsx`,渲染的 UI 如下:
|
233
|
+
当访问任何匹配不到的路径时(如 `/blog/a`),都会渲染 `routes/blog/$.tsx` 组件,因为这里有 `layout.tsx`,渲染的 UI 如下:
|
234
234
|
|
235
235
|
```tsx
|
236
236
|
<RootLayout>
|
@@ -352,7 +352,7 @@ Modern.js 建议必须有根 Layout 和根 Loading。
|
|
352
352
|
|
353
353
|
### 路由重定向
|
354
354
|
|
355
|
-
|
355
|
+
可以使用 [`Data Loader`](/guides/basic-features/data/data-fetch) 文件做路由的重定向。如有文件 `routes/user/page.tsx`,想对这个文件对应的路由做重定向,可以创建 `routes/user/page.data.ts` 文件:
|
356
356
|
|
357
357
|
```ts title="routes/user/page.data.ts"
|
358
358
|
import { redirect } from '@modern-js/runtime/router';
|
@@ -460,8 +460,8 @@ export const init = (context: RuntimeContext) => {
|
|
460
460
|
import { useRuntimeContext } from '@modern-js/runtime';
|
461
461
|
|
462
462
|
export default () => {
|
463
|
-
const
|
464
|
-
const { message } = context.
|
463
|
+
const context = useRuntimeContext();
|
464
|
+
const { message } = context.initialData;
|
465
465
|
|
466
466
|
return <div>{message}</div>;
|
467
467
|
};
|
@@ -492,7 +492,7 @@ export const init = (context: RuntimeContext) => {
|
|
492
492
|
|
493
493
|
### 预加载
|
494
494
|
|
495
|
-
在约定式路由下, Modern.js
|
495
|
+
在约定式路由下, Modern.js 会根据路由,自动地对路由进行分片。当用户访问具体的路由时,会自动加载对应的分片,这样可以有效地减少首屏加载的时间。但这也带来了一个问题,当用户访问一个路由时,如果该路由对应的分片还未加载完成,就会出现白屏的情况。
|
496
496
|
这种情况下你可以通过定义 `Loading` 组件,在静态资源加载完成前,展示一个自定义的 `Loading` 组件。
|
497
497
|
|
498
498
|
为了进一步提升用户体验,减少 loading 的时间,Modern.js 支持在 Link 组件上定义 `prefetch` 属性,可以提前对静态资源和数据进行加载:
|
@@ -550,7 +550,7 @@ export default () => {
|
|
550
550
|
```
|
551
551
|
|
552
552
|
:::note
|
553
|
-
Modern.js 默认对约定式路由做了一系列资源加载及渲染上的优化,并且提供了开箱即用的 SSR
|
553
|
+
Modern.js 默认对约定式路由做了一系列资源加载及渲染上的优化,并且提供了开箱即用的 SSR 能力。而在使用自控路由时,这些能力都需要开发者自行封装。我们推荐开发者使用约定式路由。
|
554
554
|
:::
|
555
555
|
|
556
556
|
## 其他路由方案
|
@@ -52,7 +52,7 @@ Modern.js 能为开发者提供极致的**开发体验(Development Experience
|
|
52
52
|
- 🪜 **渐进式**:使用最精简的模板创建项目,通过生成器逐步开启插件功能,定制解决方案。
|
53
53
|
- 🏠 **一体化**:开发与生产环境 Web Server 唯一,CSR 和 SSR 同构开发,函数即接口的 API 服务调用。
|
54
54
|
- 📦 **开箱即用**:默认 TS 支持,内置构建、ESLint、调试工具,全功能可测试。
|
55
|
-
- 🌏
|
55
|
+
- 🌏 **周边生态**:自研状态管理、微前端、模块打包等周边需求。
|
56
56
|
- 🕸 **多种路由模式**:包含自控路由、基于文件约定的路由(嵌套路由)等。
|
57
57
|
|
58
58
|
## 和其他框架的对比
|
@@ -83,12 +83,6 @@ Modern.js 支持使用 [styled-components](https://styled-components.com/),请
|
|
83
83
|
|
84
84
|
如果你需要使用其他 CSS-in-JS 方案,可以自行集成到你的项目中。
|
85
85
|
|
86
|
-
## 测试框架
|
87
|
-
|
88
|
-
Modern.js 支持使用 [Jest](https://jestjs.io/) 进行单元测试或集成测试。该功能为可选功能,请参考[「使用 Jest 测试」](/guides/advanced-features/testing) 启用。
|
89
|
-
|
90
|
-
如果你需要使用 [Vitest](https://vitest.dev/) 或其他测试框架,可以自行集成到你的项目中。
|
91
|
-
|
92
86
|
## 组件库
|
93
87
|
|
94
88
|
Modern.js 可以与社区中任意的 React 组件库搭配使用,比如 [MUI](https://mui.com/)、[Ant Design](https://ant.design/)、[Arco Design](https://github.com/arco-design/arco-design)、[Semi Design](https://semi.design/)、[Radix UI](https://www.radix-ui.com/) 等。
|
@@ -105,7 +105,7 @@ interface IAppContext {
|
|
105
105
|
/** 服务端路由信息 */
|
106
106
|
serverRoutes: ServerRoute[];
|
107
107
|
/** 当前项目类型 */
|
108
|
-
toolsType?: 'app-tools' | 'module-tools'
|
108
|
+
toolsType?: 'app-tools' | 'module-tools';
|
109
109
|
/** 当前使用的打包工具类型 */
|
110
110
|
bundlerType?: 'webpack' | 'rspack' | 'esbuild';
|
111
111
|
}
|
@@ -20,7 +20,6 @@ Options:
|
|
20
20
|
-d,--debug 开启 Debug 模式,打印调试日志信息 (default: false)
|
21
21
|
--mwa 一键创建 Web 应用(使用默认配置) (default: false)
|
22
22
|
--module 一键创建 Module 应用(使用默认配置) (default: false)
|
23
|
-
--monorepo 一键创建 Monorepo 应用(使用默认配置) (default: false)
|
24
23
|
--generator <generator> 使用自定义生成器
|
25
24
|
-p, --plugin <plugin> 使用生成器插件创建新的工程方案类型或定制化 Modern.js 工程方案 (default: [])
|
26
25
|
--dist-tag <distTag> 生成项目时生成器使用特殊的 npm Tag (default: "")
|
@@ -89,10 +88,6 @@ npx @modern-js/create@latest --config '{"packageManager": "pnpm"}'
|
|
89
88
|
|
90
89
|
快速创建 Npm 模块项目。
|
91
90
|
|
92
|
-
## --monorepo
|
93
|
-
|
94
|
-
快速创建 Monorepo 项目。
|
95
|
-
|
96
91
|
## -p, --plugin \<plugin>
|
97
92
|
|
98
93
|
指定生成器插件。
|
@@ -4,7 +4,7 @@ sidebar_position: 1
|
|
4
4
|
|
5
5
|
# 使用
|
6
6
|
|
7
|
-
Modern.js 提供了 `@modern-js/create` 工具用于创建 Modern.js 提供的工程方案项目,例如 [Web 应用](https://modernjs.dev/)、[Npm 模块](https://modernjs.dev/module-tools)
|
7
|
+
Modern.js 提供了 `@modern-js/create` 工具用于创建 Modern.js 提供的工程方案项目,例如 [Web 应用](https://modernjs.dev/)、[Npm 模块](https://modernjs.dev/module-tools)。
|
8
8
|
|
9
9
|
下面将介绍 `@modern-js/create` 的使用姿势。
|
10
10
|
|
@@ -47,12 +47,3 @@ npx @modern-js/create@latest npm-module
|
|
47
47
|
? 请选择开发语言 TS
|
48
48
|
? 请选择包管理工具 pnpm
|
49
49
|
```
|
50
|
-
|
51
|
-
### 创建 Monorepo
|
52
|
-
|
53
|
-
```bash
|
54
|
-
npx @modern-js/create@latest monorepo
|
55
|
-
? 请选择你想创建的工程类型 Monorepo
|
56
|
-
? 请选择包管理工具 pnpm
|
57
|
-
```
|
58
|
-
|
@@ -60,8 +60,6 @@ sidebar_position: 3
|
|
60
60
|
|
61
61
|
- 启用「微前端」模式 -- micro_frontend
|
62
62
|
|
63
|
-
- 启用「单元测试 / 集成测试」功能 -- test
|
64
|
-
|
65
63
|
- 启用「基于 UA 的 Polyfill」功能 -- polyfill
|
66
64
|
|
67
65
|
- 启用「全局代理」 -- proxy
|
@@ -111,37 +109,8 @@ sidebar_position: 3
|
|
111
109
|
|
112
110
|
选项:
|
113
111
|
|
114
|
-
- 启用「单元测试 / 集成测试」功能 -- test
|
115
|
-
|
116
112
|
- 启用 「Tailwind CSS」 支持 -- tailwindcss
|
117
113
|
|
118
114
|
- 启用「Storybook」 -- storybook
|
119
115
|
|
120
116
|
- 启用「Runtime API」 -- runtime_api
|
121
|
-
|
122
|
-
## Monorepo
|
123
|
-
|
124
|
-
### sub_solution
|
125
|
-
|
126
|
-
问题:请选择你想创建的工程类型
|
127
|
-
|
128
|
-
选项:
|
129
|
-
|
130
|
-
- Web 应用 -- mwa
|
131
|
-
- Npm 模块 -- module
|
132
|
-
|
133
|
-
### packageName
|
134
|
-
|
135
|
-
问题:请填写子项目名称
|
136
|
-
|
137
|
-
:::info
|
138
|
-
子项目的 `package.json` 的 name 字段值,该配置值为字符串类型。
|
139
|
-
:::
|
140
|
-
|
141
|
-
### packagePath
|
142
|
-
|
143
|
-
问题:请填写子项目目录名称
|
144
|
-
|
145
|
-
:::info
|
146
|
-
子项目基于 apps 或者 packages 目录的子目录名称,该字段为字符串类型。
|
147
|
-
:::
|
@@ -4,7 +4,7 @@ sidebar_position: 1
|
|
4
4
|
|
5
5
|
# 使用
|
6
6
|
|
7
|
-
在 Web 应用、 Npm
|
7
|
+
在 Web 应用、 Npm 模块中,我们提供了 `new` 命令用于创建项目元素、开启功能和创建子项目。
|
8
8
|
|
9
9
|
## Web 应用
|
10
10
|
|
@@ -72,23 +72,3 @@ npm run new
|
|
72
72
|
```
|
73
73
|
|
74
74
|
执行完成后将会在项目安装 Storybook 插件相关依赖,增加 `storybook` 命令,创建 `stories` 目录用于 Storybook 模块的开发并提供提示信息用于注册 Storybook 插件。
|
75
|
-
|
76
|
-
## Monorepo
|
77
|
-
|
78
|
-
Monorepo 项目通过 `@modern-js/monorepo-tools` 提供 new 命令。
|
79
|
-
|
80
|
-
new 命令提供了创建子项目的能力。
|
81
|
-
|
82
|
-
例如:
|
83
|
-
|
84
|
-
创建 Web 应用子项目:
|
85
|
-
|
86
|
-
```bash
|
87
|
-
? 请选择你想创建的工程类型 Web 应用
|
88
|
-
? 请填写子项目名称 web_app
|
89
|
-
? 请填写子项目目录名称 web_app
|
90
|
-
? 请选择开发语言 TS
|
91
|
-
? 请选择构建工具 webpack
|
92
|
-
```
|
93
|
-
|
94
|
-
执行完成后将会在项目 apps 目录创建 `web_app` 的子项目,在子项目目录中依然可以执行 new 命令创建项目元素和开启功能。
|