@modern-js/main-doc 2.0.0-beta.6 → 2.0.0-canary.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (58) hide show
  1. package/.turbo/turbo-build.log +1 -1
  2. package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/src/index_.md +1 -1
  3. package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/src/pages.md +1 -1
  4. package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/src/routes.md +86 -0
  5. package/en/docusaurus-plugin-content-docs/current/components/global-proxy-config.md +74 -0
  6. package/en/docusaurus-plugin-content-docs/current/components/global-proxy.md +28 -0
  7. package/en/docusaurus-plugin-content-docs/current/configure/app/dev/proxy.md +2 -72
  8. package/en/docusaurus-plugin-content-docs/current/configure/app/source/entries.md +0 -2
  9. package/en/docusaurus-plugin-content-docs/current/configure/app/tools/tailwindcss.md +16 -22
  10. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/bff/_category_.json +8 -0
  11. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/bff/bff-proxy.md +27 -0
  12. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/bff/frameworks.md +148 -0
  13. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/bff/function.md +218 -0
  14. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/bff/index.md +20 -0
  15. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/bff/type.md +43 -0
  16. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/code-split.md +77 -0
  17. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/compatibility.md +76 -0
  18. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/eslint.md +145 -0
  19. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/index.md +12 -0
  20. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/low-level.md +46 -0
  21. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/ssg.md +128 -0
  22. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/ssr.md +306 -0
  23. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/testing.md +46 -0
  24. package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/web-server.md +57 -0
  25. package/en/docusaurus-plugin-content-docs/current/guides/basic-features/alias.md +67 -0
  26. package/en/docusaurus-plugin-content-docs/current/guides/basic-features/css/tailwindcss.md +30 -35
  27. package/en/docusaurus-plugin-content-docs/current/guides/basic-features/data-fetch.md +400 -0
  28. package/en/docusaurus-plugin-content-docs/current/guides/basic-features/env-vars.md +166 -0
  29. package/en/docusaurus-plugin-content-docs/current/guides/basic-features/html.md +235 -0
  30. package/en/docusaurus-plugin-content-docs/current/guides/basic-features/mock.md +78 -0
  31. package/en/docusaurus-plugin-content-docs/current/guides/basic-features/proxy.md +60 -0
  32. package/en/docusaurus-plugin-content-docs/current/guides/get-started/quick-start.md +2 -4
  33. package/package.json +3 -3
  34. package/zh/apis/app/hooks/src/index_.md +1 -1
  35. package/zh/apis/app/hooks/src/pages.md +1 -1
  36. package/zh/apis/app/hooks/src/routes.md +89 -0
  37. package/zh/components/debug-app.md +1 -2
  38. package/zh/components/global-proxy-config.md +70 -0
  39. package/zh/configure/app/dev/proxy.md +2 -70
  40. package/zh/configure/app/source/entries.md +1 -3
  41. package/zh/configure/app/tools/tailwindcss.md +16 -23
  42. package/zh/guides/advanced-features/bff/function.md +37 -19
  43. package/zh/guides/advanced-features/code-split.md +28 -20
  44. package/zh/guides/advanced-features/compatibility.md +24 -14
  45. package/zh/guides/advanced-features/ssg.md +1 -47
  46. package/zh/guides/advanced-features/ssr.md +1 -1
  47. package/zh/guides/advanced-features/testing.md +2 -2
  48. package/zh/guides/basic-features/alias.md +5 -5
  49. package/zh/guides/basic-features/css/tailwindcss.md +31 -35
  50. package/zh/guides/basic-features/data-fetch.md +7 -6
  51. package/zh/guides/basic-features/env-vars.md +2 -2
  52. package/zh/guides/basic-features/html.md +62 -137
  53. package/zh/guides/basic-features/mock.md +8 -9
  54. package/zh/guides/basic-features/proxy.md +2 -2
  55. package/zh/guides/basic-features/routes.md +37 -3
  56. package/zh/guides/get-started/quick-start.md +1 -2
  57. package/zh/guides/topic-detail/framework-plugin/implement.md +54 -6
  58. package/zh/guides/topic-detail/micro-frontend/c02-development.md +1 -1
@@ -3,86 +3,60 @@ title: HTML 模板
3
3
  sidebar_position: 9
4
4
  ---
5
5
 
6
- Modern.js 提供了 `jsx` `ejs` 两种方式用于自定义 html 模板。推荐使用 `jsx` 语法,让写模板跟写组件一样丝滑。
6
+ Modern.js 提供了 **JSX 语法**和**HTML(Ejs) 语法**两种方式用于自定义 HTML 模板。
7
7
 
8
- ## jsx
8
+ ## JSX 语法
9
9
 
10
- ### 使用说明
10
+ Modern.js 约定,在 `src/` 目录下,或在入口目录下,可以创建 `Document.[jt]sx` 并默认导出组件。该组件的渲染结果可以作为入口的 HTML 模板。
11
11
 
12
- #### 引入
13
- ```tsx
14
- import {
15
- Html,
16
- Root,
17
- Head,
18
- DocumentContext,
19
- Body,
20
- } from '@modern-js/runtime/document';
12
+ 例如以下目录结构:
13
+
14
+ ```bash
15
+ .
16
+ ├── src
17
+ │   ├── Document.tsx
18
+ │   ├── entry-a
19
+ │   │   ├── Document.tsx
20
+ │   │   └── routes
21
+ │   ├── entry-b
22
+ │   │   └── routes
23
+ │   └── modern-app-env.d.ts
21
24
  ```
22
25
 
23
- #### 导出
24
- ```tsx
25
- export default Document() {}
26
+ `entry-a` 会优先使用当前入口下的 `Docoument.[jt]sx` 文件。如果当前入口没有 `Document.[jt]sx` 文件,例如 `entry-b`,则会查找根目录下的 `Document.[jt]sx` 文件。
26
27
 
27
- ```
28
+ 如果还没有,则会兜底到传统模板的逻辑。
28
29
 
29
- #### 文件位置
30
+ ### HTML 组件
30
31
 
31
- Document 文件,默认在应用根目录下:
32
+ Modern.js 提供了一些列渲染页面的组件,用来帮助开发者生成模板,可以从 `@modern-js/runtime/document` 中导出这些组件:
32
33
 
33
- ```bash
34
- .
35
- ├── src
36
- │ ├── modern-app-env.d.ts
37
- │ ├── myapp
38
- │ │ └── routes
39
- │ │ ├── index.css
40
- │ │ ├── layout.tsx
41
- │ │ ├── Document.tsx
42
- │ │ └── page.tsx
43
- │ ├── new-entry
44
- │ │ └── routes
45
- │ │ ├── index.css
46
- │ │ ├── layout.tsx
47
- │ │ ├── Document.tsx
48
- │ │ └── page.tsx
49
- │ └── Document.tsx
50
- ├── modern.config.ts
51
- ├── package.json
52
- ├── pnpm-lock.yaml
53
- ├── README.md
54
- └── tsconfig.json
34
+ ```tsx
35
+ import { Html, Body, Root, Head, Scripts } from '@modern-js/runtime/document';
55
36
  ```
56
37
 
57
- 多 entry 场景构建时,优先 entry 的根目录下的 Docoument.tsx 文件。如果当前 entry 没有 Document.tsx 文件,则会查找根目录下的 Document.tsx 文件。
58
- 如果还没有,则会 fallback 到 `html 模板` 的逻辑。
59
-
60
- #### 子组件
38
+ 这些组件分别渲染:
61
39
 
62
- Document 模板共提供了 `Html`、`Root` `Head` `Body` 渲染页面的组件,以及 `DocumentContext` 等提供
63
- 分别渲染:
64
- - `Html`: 提供 html 原生 dom。并计算出 `DocumentStructrueContext` 的值,将 `Html` 的结构传递给子组件,判断其它子组件是否默认渲染。
40
+ - `Html`:提供原生 HTML Element 的能力,并能默认渲染开发者未添加的必须的组件。`<Head>` 和 `<Body>` 是必须要存在的,其它组件可以按需选择合适的组件进行组装。
65
41
 
66
- - `Body`: 渲染生成 `body` 节点。其子元素包含 `Root` 组件。支持其它元素同时作为子元素,例如页脚。
42
+ - `Body`:提供原生 Body Element 的能力,内部需要包含 `<Root>` 组件,也支持其它元素同时作为子元素,例如添加页脚。
67
43
 
68
- - `Root`: 渲染的根节点 `<div id='root'></div>`。默认根节点的 `id = 'root'`。可以设置 props.rootId 来更改 id 属性。子元素,也会被渲染进 DOM 里,随着 react 渲染完成,会替换掉,一般用来实现全局 loading
44
+ - `Root`:渲染的根节点 `<div id='root'></div>`。默认根节点的 `id = 'root'`。可以设置 `props.rootId` 来更改 id 属性。可以添加子组件,也会被渲染到 HTML 模板中,当 React 渲染完成后会被覆盖,一般用来实现全局 Loading
69
45
 
70
- - `Head`: 渲染生成 `head` 节点。会自动填充 meta 元素,以及 `Scripts` 组件。
46
+ - `Head`:提供原生 Head Element 的能力,并会自动填充 `<meta>`,以及 `<Scripts>` 组件。
71
47
 
72
- - `Scripts`: 将构建产生的 script 标签渲染到该位置。用于调整构建产物的位置,默认放在 `Head` 组件里,用于
48
+ - `Scripts`:构建产生的 script 内容,可用于调整构建产物的位置,默认放在 `<Head>` 组件中。
73
49
 
74
- `Html` 组件中,`Head` 和 `Body` 是必须要存在的,其它组件可以按需选择合适的组件进行组装。
50
+ ### 模板参数
75
51
 
76
- #### 模板参数
52
+ 因为是 JSX 形式,`Document.[jt]sx` 里,可以比较自由的在组件内使用各种变量去赋值给各种自定义组件。
77
53
 
78
- 因为是 JSX 形式,Document.tsx 里,可以比较自由的在组件内使用各种变量去赋值给各种自定义组件。
79
- 但同时 Document 自身也提供了 `DocumentContext` context 来提供一些配置、环境参数,方便直接获取。主要以下参数:
54
+ Modern.js 也提供了 `DocumentContext` 来提供一些配置、环境参数,方便直接获取。主要以下参数:
80
55
 
81
56
  - `processEnv`:提供构建时的 `process.env`
82
- - `config`: Modern.js 项目的配置。目前只暴露出 output 相关的配置
83
- - `entryName`: 当前的 entry 名。
84
- - `templateParams`: html 模板的参数,由 builder 提供。对应 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 的 `templateParameters` 配置项最终获取到的结果。不建议使用!
85
-
57
+ - `config`:Modern.js 项目的配置。目前只暴露出 output 相关的配置
58
+ - `entryName`:当前的入口名
59
+ - `templateParams`:HTML 模板的参数(为了兼容传统模板,不推荐使用)
86
60
 
87
61
  ### 示例
88
62
 
@@ -92,12 +66,11 @@ import {
92
66
  Html,
93
67
  Root,
94
68
  Head,
95
- DocumentContext,
96
69
  Body,
70
+ Scripts,
71
+ DocumentContext
97
72
  } from '@modern-js/runtime/document';
98
- import Script from '@/components/Script';
99
73
 
100
- // 默认导出
101
74
  export default function Document(): React.ReactElement {
102
75
  // DocumentContext 提供一些构建时的参数
103
76
  const {
@@ -109,34 +82,23 @@ export default function Document(): React.ReactElement {
109
82
  return (
110
83
  <Html>
111
84
  <Head>
112
- // Head 组件支持自定义子元素。包括 link, script
113
85
  <link href="https://modernjs.dev">Modern.js</link>
114
- <script
115
- // inline script 的脚本需要如下处理
116
- dangerouslySetInnerHTML={{
117
- __html: `window.b = 22`,
118
- }}
119
- ></script>
120
86
  </Head>
121
87
  <Body>
122
- // rootId 可以更改根元素的 id
123
88
  <Root rootId="root">
124
- // Root 支持子元素
125
89
  <h1 style={{ color: 'red' }}>以下为构建时传过来的参数:</h1>
126
90
  <h2> entryName:{entryName}</h2>
127
91
  <h2> title:{htmlConfig.title}</h2>
128
92
  <h2> rootId: {templateParams.mountId}</h2>
129
93
  </Root>
130
- // Body 组件支持 Root 以外增加不同的组件,共同组成页面
131
94
  <h1>bottom</h1>
132
95
  </Body>
133
96
  </Html>
134
97
  );
135
98
  }
136
-
137
99
  ```
138
100
 
139
- 以上文件,将会生成以下 html 文件:
101
+ 以上 JSX 组件,将会生成以下 HTML 模板:
140
102
 
141
103
  ```html
142
104
  <!DOCTYPE html>
@@ -162,7 +124,6 @@ export default function Document(): React.ReactElement {
162
124
  src="/static/js/packages_runtime_plugin-router-legacy_dist_js_treeshaking_runtime_index_js-packages_runtime_p-28f4c9.js"></script>
163
125
  <script defer src="/static/js/sub.js"></script>
164
126
  <link href="https://www.baidu.com" />
165
- <script>window.b = 22</script>
166
127
  </head>
167
128
 
168
129
  <body>
@@ -177,26 +138,23 @@ export default function Document(): React.ReactElement {
177
138
  <!--<?- chunksMap.js ?>-->
178
139
  <!--<?- SSRDataScript ?>-->
179
140
  </body>
180
-
181
141
  </html>
182
142
  ```
183
143
 
184
- ## ejs
144
+ ## Html 语法
185
145
 
186
- Modern.js 同时支持了使用 `ejs` 语法编写模板,当项目中,没有编写 `Document.[j|t]sx` 文件时,将自动回退至 `ejs` HTML 模板。
146
+ Modern.js 也支持 HTML 语法。默认情况下,Modern.js 的应用工程中会内置一份 HTML 模板,用于生成 HTML 代码。
187
147
 
188
- 默认情况下,Modern.js 的应用工程中会内置一份 HTML 模板,用于生成 HTML 代码。
148
+ 基于 HTML 语法的模板,Modern.js 提供了 **自定义 HTML 片段**和**完全自定义 HTML 模板**两种方式来自定义模板。
189
149
 
190
- Modern.js 提供了**「自定义 HTML 片段」**和**「完全自定义 HTML 模板」**两种方式来自定义模板。
191
-
192
- ## 自定义 HTML 片段
150
+ ### 自定义 HTML 片段
193
151
 
194
152
  在应用根目录下,创建 `config/html/` 目录,该目录下支持创建四种 HTML 片段。
195
153
 
196
- - `top.(html|ejs)`
197
- - `head.(html|ejs)`
198
- - `body.(html|ejs)`
199
- - `bottom.(html|ejs)`
154
+ - `top.html`
155
+ - `head.html`
156
+ - `body.html`
157
+ - `bottom.html`
200
158
 
201
159
  **这些片段将按位置注入到默认的 HTML 模板中。**
202
160
 
@@ -226,54 +184,19 @@ Modern.js 提供了**「自定义 HTML 片段」**和**「完全自定义 HTML
226
184
  </html>
227
185
  ```
228
186
 
229
- 代码片段支持 [EJS](https://ejs.co/) 语法(默认使用 [Lodash template](https://lodash.com/docs/4.17.15#template) 语法)。
187
+ 代码片段支持使用 [Lodash template](https://lodash.com/docs/4.17.15#template) 语法。
230
188
 
231
- 例如,新增 `head.ejs` 文件,并添加一个自定义标签:
232
-
233
- ```html title="config/html/head.ejs"
234
- <% if (process.env.NODE_ENV === 'production') { %>
235
- <meta name='env' content="production">
236
- <% } else { %>
237
- <meta name='env' content="development">
238
- <% } %>
239
- ```
240
-
241
- 或在 `body.html` 里插入一个外链脚本:
189
+ 例如在 `body.html` 里插入一个外链脚本:
242
190
 
243
191
  ```html title="config/html/body.html"
244
192
  <script src="//example.com/assets/a.js"></script>
245
193
  ```
246
194
 
247
- :::info 自定义 HTML 片段不支持修改 title 标签
248
- 自定义 HTML 片段的实现方式是将片段与框架内置的模板进行合并,由于框架的默认模板中已经存在 title 标签,因此自定义 HTML 模板中的 title 标签无法生效,请通过 [html.title](/docs/configure/app/html/title) 来修改页面标题。
195
+ :::info
196
+ 自定义 HTML 片段的实现方式是将片段与框架内置的模板进行合并,由于框架的默认模板中已经存在 `<title>`,因此自定义 HTML 模板中的 title 标签无法生效,请通过 [html.title](/docs/configure/app/html/title) 来修改页面标题。
249
197
  :::
250
198
 
251
- ### 模板参数
252
-
253
- 模板中使用的参数可以通过 [html.templateParameters](/docs/configure/app/html/template-parameters) 配置项来定义。
254
-
255
-
256
- ### 按入口设置
257
-
258
- `config/html/` 目录中的 HTML 片段对应用中的所有入口都生效。如果希望按入口自定义 HTML 片段,可以在 `config/html/` 目录下新建一个以**入口名**命名的目录,然后在这个目录中自定义 HTML 片段。
259
-
260
- 例如,如下设置的 HTML 片段仅对入口 `entry1` 生效:
261
-
262
- ```html
263
- .
264
- ├── config/
265
- │ └── html/
266
- │ └── entry1
267
- │ ├── head.html
268
- │ └── body.html
269
- └── src/
270
- ├── entry1/
271
- │ └── App.jsx
272
- └── entry2/
273
- └── App.jsx
274
- ```
275
-
276
- ## 完全自定义 HTML 模板
199
+ ### 完全自定义 HTML 模板
277
200
 
278
201
  某些情况下,HTML 片段无法满足自定义需求,Modern.js 提供了完全自定义方式。
279
202
 
@@ -281,30 +204,32 @@ Modern.js 提供了**「自定义 HTML 片段」**和**「完全自定义 HTML
281
204
  通常不建议直接覆盖默认的 HTML 模板,可能会失去一部分功能选项。即使需要替换,建议以内置模板为基础,按需修改。
282
205
  :::
283
206
 
284
-
285
- ### 配置方式
286
-
287
- 在 `config/html/` 目录下,创建 `index.(html|ejs)` 文件。
288
-
289
- 该文件将替代默认的 HTML 模板。
207
+ 在 `config/html/` 目录下,创建 `index.html` 文件,该文件将替代默认的 HTML 模板。
290
208
 
291
209
  :::info 注
292
210
  内部默认 HTML 模板可以在 `node_modules/.modern-js/${entryName}/index.html` 中查看。
293
211
  :::
294
212
 
295
- 如果仅需要为单一入口设置 HTML 模板,需要将 `index.(html|ejs)` 文件,放置到 `config/html/` 目录下以**入口名**命名的目录中。
213
+ ### 模板参数
296
214
 
297
- 例如,如下设置的 HTML 模板 `index.html` 仅对入口 `entry1` 生效:
215
+ 模板中使用的参数可以通过 [html.templateParameters](/docs/configure/app/html/template-parameters) 配置项来定义。
216
+
217
+ ### 按入口设置
218
+
219
+ `config/html/` 目录中的 HTML 片段对应用中的所有入口都生效。如果希望按入口自定义 HTML 片段,可以在 `config/html/` 目录下新建一个以**入口名**命名的目录,然后在这个目录中自定义 HTML 片段。
220
+
221
+ 例如,如下设置的 HTML 片段仅对入口 `entry1` 生效:
298
222
 
299
223
  ```html
300
224
  .
301
225
  ├── config/
302
226
  │ └── html/
303
227
  │ └── entry1
304
- └── index.html
228
+ ├── head.html
229
+ │ └── body.html
305
230
  └── src/
306
231
  ├── entry1/
307
- │ └── App.jsx
232
+ │ └── routes
308
233
  └── entry2/
309
- └── App.jsx
234
+ └── routes
310
235
  ```
@@ -7,26 +7,25 @@ Modern.js 提供了快速生成 Mock 数据的功能,能够让前端独立自
7
7
 
8
8
  ## Mock 文件
9
9
 
10
- 约定当 `config/mock` 目录下存在 `index.[jt]s` 时,会自动开启 Mock 功能,如下:
10
+ 约定当 `config/mock` 目录下存在 `index.[jt]s` 时,会自动开启 Mock 功能,如下:
11
11
 
12
12
  ```bash
13
13
  .
14
14
  ├── config
15
15
  │ └── mock
16
- ├── a.json
17
- │ └── index.js
16
+ └── index.ts
18
17
  ├── src
19
- │ └── App.jsx
20
- └── modern.config.js
18
+ │ └── App.tsx
19
+ └── modern.config.ts
21
20
  ```
22
21
 
23
- ## Mock 文件编写
22
+ ## 编写 Mock 文件
24
23
 
25
- `./config/mock/index.js` 文件只需要导出一个包含所有 Mock API 的对象,对象的属性由请求配置 `method` 和 `url` 组成,对应的属性值可以为 `Object`、`Array`、`Function`:
24
+ `config/mock/index.ts` 文件只需要导出一个包含所有 Mock API 的对象,对象的属性由请求配置 `method` 和 `url` 组成,对应的属性值可以为 `Object`、`Array`、`Function`:
26
25
 
27
26
  ```js
28
27
  module.exports = {
29
- /* 属性为具体的 method 和 请求 url,值为 object 或 array作为请求的结果 */
28
+ /* 属性为具体的 method 和 请求 url,值为 object 或 array 作为请求的结果 */
30
29
  'GET /api/getInfo': { data: [1, 2, 3, 4] },
31
30
 
32
31
  /* method 默认为 GET */
@@ -44,7 +43,7 @@ module.exports = {
44
43
 
45
44
  ## 返回随机数据
46
45
 
47
- 可以在 `./config/mock/index.js` 中自主引入 [Mock.js](https://github.com/nuysoft/Mock/wiki/Getting-Started) 等库生成随机数据,例如:
46
+ 可以在 `config/mock/index.js` 中自主引入 [Mock.js](https://github.com/nuysoft/Mock/wiki/Getting-Started) 等库生成随机数据,例如:
48
47
 
49
48
  ```js
50
49
  const Mock = require('mockjs');
@@ -27,7 +27,7 @@ export default defineConfig({
27
27
  请求 `http://localhost:8080/go/api` 时,会从 [http://www.example.com/](http://www.example.com/) 返回响应内容。
28
28
 
29
29
  :::info 补充信息
30
- 配置格式可参考:【[http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)】。
30
+ 配置格式可参考:[http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)
31
31
  :::
32
32
 
33
33
  ## 全局代理
@@ -38,7 +38,7 @@ import GlobalProxy from '@site-docs/components/global-proxy.md'
38
38
 
39
39
  ## BFF 代理
40
40
 
41
- 通过配置 [`bff.proxy`](/docs/configure/app/bff/proxy) 可以代理 BFF API 请求到指定的服务上,和[开发环境代理](/docs/configure/app/dev/proxy)不同的是,它同样可以用在生产环境:
41
+ 通过配置 [`bff.proxy`](/docs/configure/app/bff/proxy) 可以代理 BFF API 请求到指定的服务上,上述两种代理不同,它同样可以用在生产环境:
42
42
 
43
43
  ```typescript title="modern.config.ts"
44
44
  export default defineConfig({
@@ -13,7 +13,7 @@ Modern.js 内置了对 [React Router 6](https://reactrouter.com/en/main) 的**
13
13
 
14
14
  以 `routes/` 为约定的入口,Modern.js 会自动基于文件系统,生成对应的路由结构。
15
15
 
16
- Modern.js 支持了业界流行的约定路由模式:**嵌套路由**,使用嵌套路由时,页面的路由 与 UI 结构是相呼应的,我们将会详细介绍这种路由模式。
16
+ Modern.js 支持了业界流行的约定式路由模式:**嵌套路由**,使用嵌套路由时,页面的路由 与 UI 结构是相呼应的,我们将会详细介绍这种路由模式。
17
17
 
18
18
  ```
19
19
  /user/johnny/profile /user/johnny/posts
@@ -26,11 +26,30 @@ Modern.js 支持了业界流行的约定路由模式:**嵌套路由**,使用
26
26
  +------------------+ +-----------------+
27
27
  ```
28
28
 
29
+
29
30
  ### 路由文件约定
30
31
 
31
- `routes/` 目录下有两个文件约定 `layout.[jt]sx` 和 `page.[jt]sx`(后面简写为 `.tsx`)。这两个文件决定了应用的布局层次,其中 `layout.tsx` 中作为布局组件,`page.tsx` 作为内容组件,是整个路由表的叶子节点。
32
+ 在`routes/` 目录下,目录名会作为路由 url 的映射,Modern.js 有两个文件约定 `layout.[jt]sx` 和 `page.[jt]sx`(后面简写为 `.tsx`)。这两个文件决定了应用的布局层次,其中 `layout.tsx` 中作为布局组件,`page.tsx` 作为内容组件,是整条路由的叶子节点(一条路由有且仅有一个叶子节点,且必须以叶子节点结尾)。
33
+
34
+ 例如以下目录结构:
35
+
36
+ ```bash
37
+ .
38
+ └── routes
39
+ ├── page.tsx
40
+ └── user
41
+ └── page.tsx
42
+ ```
43
+
44
+ 会产出下面两条路由:
45
+ - `/`
46
+ - `/user`
32
47
 
33
- 例如,这里 `routes/layout.tsx` 会作为 `/` 路由下所有组件的布局组件使用:
48
+ 当添加 `layout.tsx` 后, 假设有以下目录
49
+
50
+ :::info
51
+ 这里 `routes/layout.tsx` 会作为 `/` 路由下所有组件的布局组件使用, `routes/user/layout.tsx` 会作为 `/user` 路由下所有路由组件的布局组件使用。
52
+ :::
34
53
 
35
54
  ```bash
36
55
  .
@@ -64,6 +83,18 @@ Modern.js 支持了业界流行的约定路由模式:**嵌套路由**,使用
64
83
 
65
84
  `<Layout>` 组件是指 `routes/` 目录下所有 `layout.tsx` 文件,它们表示对应路由片段的布局,使用 `<Outlet>` 表示子组件。
66
85
 
86
+ ```tsx title=routes/layout.tsx
87
+ import { Link, Outlet, useLoaderData } from '@modern-js/runtime/router';
88
+
89
+ export default () => {
90
+ return (
91
+ <>
92
+ <Outlet></Outlet>
93
+ </>
94
+ )
95
+ }
96
+ ```
97
+
67
98
  :::note
68
99
  `<Outlet>` 是 React Router 6 中新的 API,详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
69
100
  :::
@@ -130,6 +161,8 @@ Modern.js 支持了业界流行的约定路由模式:**嵌套路由**,使用
130
161
 
131
162
  在组件中,可以通过 [useParams](/docs/apis/app/runtime/router/#useparams) 获取对应命名的参数。
132
163
 
164
+ 在 loader 中,params 会作为 [loader](/docs/guides/basic-features/data-fetch#loader-函数) 的入参,通过 `params.xxx` 可以获取。
165
+
133
166
  ### 无路径布局
134
167
 
135
168
  当目录名以 __ 开头时,对应的目录名不会转换为实际的路由路径,例如以下文件目录:
@@ -217,6 +250,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由,`__auth/layout.tsx` 组
217
250
  ```
218
251
  :::info
219
252
  当目录的 layout 组件不存在时,该目录下的 loading 组件也不会生效。
253
+ Modern.js 建议必须有根 layout 和根 loading。
220
254
  :::
221
255
 
222
256
  当路由从 `/` 跳转到 `/blog` 时,如果 `blog/page` 组件的 JS Chunk 还未加载,则会先展示 `loading.tsx` 中导出的组件 UI。
@@ -120,8 +120,7 @@ Starting the modern server...
120
120
  info App running at:
121
121
 
122
122
  > Local: http://localhost:8080/
123
- > Network: http://10.94.58.87:8080/
124
- > Network: http://10.254.68.105:8080/
123
+ > Network: http://192.168.0.1:8080/
125
124
  ```
126
125
 
127
126
  在浏览器中打开 `http://localhost:8000/`,内容应该和 `pnpm run dev` 时一致。
@@ -30,11 +30,23 @@ const MyPlugin = {
30
30
  };
31
31
  ```
32
32
 
33
- 另外,在插件中,允许配置与其他插件的执行顺序,详情可以参考[插件关系](/docs/guides/topic-detail/framework-plugin/relationship)。
33
+ 另外,在插件中,允许配置与其他插件的执行顺序。详情可以参考[插件关系](/docs/guides/topic-detail/framework-plugin/relationship)。
34
34
 
35
35
  ### 插件类型
36
36
 
37
- 使用 TypeScript 时,可以引入内置的 `CliPlugin` 类型,为插件提供正确的类型推导:
37
+ Modern-js 支持多种工程开发,如应用工程(app-tools), 模块工程(module-tools)等。
38
+
39
+ 为了兼顾不同工程开发的差异和通性,Modern-js 将插件如下图进行组织:
40
+
41
+ ![plugin-relationship](https://lf3-static.bytednsdoc.com/obj/eden-cn/eeeh7uhbepxlpe/modern-website/plugin-relationship.jpg)
42
+
43
+ 从图可以看出,Modern-js 将插件大致分为两类:
44
+
45
+ 1. 通用插件: 插件只会包含一些基础的 Hooks
46
+
47
+ 2. 工程插件: 不同的工程开发会在通用插件的基础上扩展出自己的 Hooks, Config 等类型。
48
+
49
+ 使用 TypeScript 时,可以引入内置的 `CliPlugin` 等类型,为插件提供正确的类型推导。
38
50
 
39
51
  ```ts
40
52
  import type { CliPlugin } from '@modern-js/core';
@@ -54,19 +66,55 @@ const MyPlugin: CliPlugin = {
54
66
  };
55
67
  ```
56
68
 
57
- Modern.js 导出的 `Plugin` 类型支持泛型扩展。
69
+ 上述代码为通用插件,只包含一些基础的 Hooks。 Modern.js 支持通过泛型对插件的定义进行扩展:
70
+
71
+ ```ts
72
+ import type { CliPlugin, AppTools } from '@modern-js/app-tools';
58
73
 
59
- Modern.js 中,任意插件可以注册自己的 Hook,如果想拥有其他插件注册的 Hook 的类型,可以添加泛型:
74
+ const MyPlugin: CliPlugin<AppTools> = {
75
+ name: 'my-plugin',
76
+
77
+ setup() {
78
+ const foo = '1';
79
+
80
+ return {
81
+ afterBuild: () => {
82
+ // 在构建完成后执行逻辑
83
+ },
84
+ };
85
+ },
86
+ };
87
+ ```
88
+
89
+ 如果仔细观察 `AppTools` 这个类型,可以发现 `AppTools` 由 3 种类型构成.
90
+
91
+ ```ts
92
+ type AppTools = {
93
+ hooks: AppToolsHooks;
94
+ userConfig: AppToolsUserConfig;
95
+ normalizedConfig: AppToolsNormalizedConfig;
96
+ };
97
+ ```
98
+
99
+ 当编写插件时,插件通过泛型扩展在不同的基础上扩展自己的 Hooks 等类型:
60
100
 
61
101
  ```ts
102
+ // 通用插件上扩展
62
103
  import type { CliPlugin } from '@modern-js/core';
63
104
  import type { MyPluginHook } from 'xxx';
64
105
 
65
- const MyPlugin: CliPlugin<MyPluginHook> = {};
106
+ const MyPlugin: CliPlugin<{ hooks: MyPluginHook }> = {};
66
107
  ```
67
108
 
68
- 详细说明,请参考 [扩展 Hook](/docs/guides/topic-detail/framework-plugin/extend)。
109
+ ```ts
110
+ // 在 @modern-js/app-tools 基础上扩展
111
+ import type { CliPlugin, AppTools } from '@modern-js/app-tools';
112
+ import type { MyPluginHook } from 'xxx';
113
+
114
+ const MyPlugin: CliPlugin<AppTools & { hooks: MyPluginHook }> = {};
115
+ ```
69
116
 
117
+ 详细说明,请参考 [扩展 Hook](/docs/guides/topic-detail/framework-plugin/extend)。
70
118
 
71
119
  ### 插件配置项
72
120
 
@@ -179,7 +179,7 @@ export default () => <div>Table Page</div>;
179
179
 
180
180
  访问主应用地址 `http://localhost:8080`,效果如下:
181
181
 
182
- ![demo](https://tosv.byted.org/obj/eden-internal/ozpmyhn_lm_hymuPild/ljhwZthlaukjlkulzlp/modernjs/micro-demo.gif)
182
+ ![demo](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/micro-demo.gif)
183
183
 
184
184
  在完成了微前端整体开发流程的体验后,你可以进一步了解如何 [开发主应用](./c03-main-app.md)
185
185