@modern-js/main-doc 2.13.3 → 2.14.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/CHANGELOG.md +23 -0
- package/docs/en/apis/app/hooks/src/routes.mdx +20 -0
- package/docs/en/components/init-app.mdx +5 -5
- package/docs/en/configure/app/server/ssr.mdx +2 -0
- package/docs/en/guides/basic-features/html.mdx +38 -38
- package/docs/zh/components/init-app.mdx +5 -5
- package/docs/zh/configure/app/server/ssr.mdx +3 -0
- package/docs/zh/guides/basic-features/html.mdx +33 -36
- package/docs/zh/guides/basic-features/routes.mdx +20 -0
- package/docs/zh/guides/topic-detail/monorepo/create-sub-project.mdx +5 -5
- package/package.json +5 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,28 @@
|
|
|
1
1
|
# @modern-js/main-doc
|
|
2
2
|
|
|
3
|
+
## 2.14.0
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 60a81d0: feat: add ssr.inlineScript for use inline json instead inline script when ssr
|
|
8
|
+
feat: 添加 ssr.inlineScript 用于在 ssr 模式下使用内联 json 而不是内联脚本
|
|
9
|
+
- 432ac8b: chore(cli): improve commands descriptions
|
|
10
|
+
|
|
11
|
+
chore(cli): 优化命令的描述文案
|
|
12
|
+
|
|
13
|
+
- de84d94: feat: add optional dynamic routes docs
|
|
14
|
+
feat: 添加可选动态路由文档
|
|
15
|
+
- Updated dependencies [fefd1c5]
|
|
16
|
+
- Updated dependencies [1f34dba]
|
|
17
|
+
- Updated dependencies [b965df2]
|
|
18
|
+
- @modern-js/builder-doc@2.14.0
|
|
19
|
+
|
|
20
|
+
## 2.13.4
|
|
21
|
+
|
|
22
|
+
### Patch Changes
|
|
23
|
+
|
|
24
|
+
- @modern-js/builder-doc@2.13.4
|
|
25
|
+
|
|
3
26
|
## 2.13.3
|
|
4
27
|
|
|
5
28
|
### Patch Changes
|
|
@@ -56,6 +56,26 @@ In the component, you can get the corresponding parameters by [useParams](/apis/
|
|
|
56
56
|
|
|
57
57
|
In the loader, params will be used as input to [loader](/guides/basic-features/data-fetch#loader-function), and the corresponding parameters can be retrieved through the property `params`.
|
|
58
58
|
|
|
59
|
+
## Dynamic Optional Routes
|
|
60
|
+
|
|
61
|
+
By using file directories named with `[$]`, the generated routes will be treated as dynamic routes. For example, the following file directory:
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
└── routes
|
|
65
|
+
├── user
|
|
66
|
+
│ └── [id$]
|
|
67
|
+
│ └── page.tsx
|
|
68
|
+
├── blog
|
|
69
|
+
│ └── page.tsx
|
|
70
|
+
└── page.tsx
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The `routes/user/[id$]/page.tsx` file will be converted to the `/user/:id?` route. All routes under `/user` will match this route, and the `id` parameter is optional. This route is commonly used to differentiate between **creating** and **editing**.
|
|
74
|
+
|
|
75
|
+
In the component, you can get the corresponding named parameters using [useParams](/apis/app/runtime/router/router#useparams).
|
|
76
|
+
|
|
77
|
+
In the loader, params will be passed as an argument to the [loader](/guides/basic-features/data-fetch#loader-函数), and you can get them through `params.xxx`.
|
|
78
|
+
|
|
59
79
|
## Layout component
|
|
60
80
|
|
|
61
81
|
As in the example below, you can add a common layout component for all routing components by adding `layout.tsx`
|
|
@@ -13,11 +13,11 @@ After create the project, Modern.js automatically installs dependency and create
|
|
|
13
13
|
[INFO] git repository has been automatically created
|
|
14
14
|
[INFO] Success！
|
|
15
15
|
You can run the following command in the directory of the new project:
|
|
16
|
-
pnpm run dev #
|
|
17
|
-
pnpm run build # Build the
|
|
18
|
-
pnpm run serve #
|
|
19
|
-
pnpm run lint #
|
|
20
|
-
pnpm run new #
|
|
16
|
+
pnpm run dev # Starting the dev server
|
|
17
|
+
pnpm run build # Build the app for production
|
|
18
|
+
pnpm run serve # Preview the production build locally
|
|
19
|
+
pnpm run lint # Run ESLint and automatically fix problems
|
|
20
|
+
pnpm run new # Enable optional features or add a new entry
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
:::note
|
|
@@ -27,12 +27,14 @@ When the value type is `Object`, The following properties can be configured:
|
|
|
27
27
|
|
|
28
28
|
- `mode`: `string = 'string'`, use `renderToString` rendering default. onfigure 'stream' to enable streaming rendering.
|
|
29
29
|
- `forceCSR`: `boolean = false`, forced CSR rendering is disable by default. When configured as `true`, add `?csr=true` in URL to force CSR.
|
|
30
|
+
- `inlineScript`：`boolean = true`, by default SSR data will be injected into HTML as inline scripts and directly assigned to global variables. Configure as `false` to inject JSON instead of directly assigning.
|
|
30
31
|
|
|
31
32
|
```ts title="modern.config.ts"
|
|
32
33
|
export default defineConfig({
|
|
33
34
|
server: {
|
|
34
35
|
forceCSR: true,
|
|
35
36
|
mode: 'stream',
|
|
37
|
+
inlineScript: false,
|
|
36
38
|
},
|
|
37
39
|
});
|
|
38
40
|
```
|
|
@@ -48,6 +48,8 @@ These components are rendered:
|
|
|
48
48
|
|
|
49
49
|
- `Scripts`: The script content generated by the webpack, which can be used to adjust the position of the bundle result, is placed in the `<Head>` component by default.
|
|
50
50
|
|
|
51
|
+
- `Comment`: Make the comment like `<!-- gateway -->`, could be stay to the html that final render.
|
|
52
|
+
|
|
51
53
|
### Template Params
|
|
52
54
|
|
|
53
55
|
Because it is in the form of JSX, in `Document.[jt]sx`, you can use various variables in the component to assign values to various custom components more freely.
|
|
@@ -68,8 +70,8 @@ import {
|
|
|
68
70
|
Root,
|
|
69
71
|
Head,
|
|
70
72
|
Body,
|
|
71
|
-
Scripts,
|
|
72
73
|
DocumentContext,
|
|
74
|
+
Comment,
|
|
73
75
|
} from '@modern-js/runtime/document';
|
|
74
76
|
|
|
75
77
|
export default function Document(): React.ReactElement {
|
|
@@ -83,13 +85,14 @@ export default function Document(): React.ReactElement {
|
|
|
83
85
|
return (
|
|
84
86
|
<Html>
|
|
85
87
|
<Head>
|
|
86
|
-
<link href="https://modernjs.dev"
|
|
88
|
+
<link href="https://modernjs.dev" />
|
|
89
|
+
<Comment>{'<!-- Need a Comment -->'}</Comment>
|
|
87
90
|
</Head>
|
|
88
91
|
<Body>
|
|
89
92
|
<Root rootId="root">
|
|
90
93
|
<h1 style={{ color: 'red' }}>Some Params: </h1>
|
|
91
|
-
<h2> entryName
|
|
92
|
-
<h2> title
|
|
94
|
+
<h2> entryName：{entryName}</h2>
|
|
95
|
+
<h2> title：{htmlConfig.title}</h2>
|
|
93
96
|
<h2> rootId: {templateParams.mountId}</h2>
|
|
94
97
|
</Root>
|
|
95
98
|
<h1>bottom</h1>
|
|
@@ -104,49 +107,46 @@ The above JSX component will generate the following HTML template:
|
|
|
104
107
|
```html
|
|
105
108
|
<!DOCTYPE html>
|
|
106
109
|
<html>
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
<meta
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
<meta
|
|
114
|
-
<meta name="
|
|
115
|
-
<meta name="
|
|
116
|
-
<meta name="
|
|
117
|
-
<meta name="
|
|
118
|
-
<
|
|
119
|
-
<script>
|
|
120
|
-
...
|
|
121
|
-
</script>
|
|
110
|
+
|
|
111
|
+
<head>
|
|
112
|
+
<meta charset="utf-8">
|
|
113
|
+
<meta name="viewport"
|
|
114
|
+
content="width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
|
|
115
|
+
<meta http-equiv="x-ua-compatible" content="ie=edge">
|
|
116
|
+
<meta name="renderer" content="webkit">
|
|
117
|
+
<meta name="layoutmode" content="standard">
|
|
118
|
+
<meta name="imagemode" content="force">
|
|
119
|
+
<meta name="wap-font-scale" content="no">
|
|
120
|
+
<meta name="format-detection" content="telephone=no">
|
|
121
|
+
<link rel="icon" href="/a.icon">
|
|
122
|
+
<script defer src="/static/js/builder-runtime.js"></script>
|
|
122
123
|
<script defer src="/static/js/lib-react.js"></script>
|
|
123
124
|
<script defer src="/static/js/lib-polyfill.js"></script>
|
|
124
125
|
<script defer src="/static/js/lib-router.js"></script>
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
<script
|
|
130
|
-
defer
|
|
131
|
-
src="/static/js/packages_runtime_plugin-router-legacy_dist_js_treeshaking_runtime_index_js-packages_runtime_p-28f4c9.js"
|
|
132
|
-
></script>
|
|
126
|
+
|
|
127
|
+
<script>
|
|
128
|
+
...
|
|
129
|
+
</script>
|
|
133
130
|
<script defer src="/static/js/sub.js"></script>
|
|
134
|
-
<link href="https://
|
|
135
|
-
|
|
131
|
+
<link href="https://modernjs.dev" />
|
|
132
|
+
<!-- Need a Comment -->
|
|
133
|
+
</head>
|
|
136
134
|
|
|
137
|
-
|
|
135
|
+
<body>
|
|
138
136
|
<div id="root">
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
137
|
+
<!--<?- html ?>-->
|
|
138
|
+
<h1 style="color:red">Some Params: </h1>
|
|
139
|
+
<h2> entryName：sub</h2>
|
|
140
|
+
<h2> title：</h2>
|
|
141
|
+
<h2> rootId: root</h2>
|
|
144
142
|
</div>
|
|
145
143
|
<h1>bottom</h1>
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
144
|
+
<!--<?- chunksMap.js ?>-->
|
|
145
|
+
<!--<?- SSRDataScript ?>-->
|
|
146
|
+
</body>
|
|
147
|
+
|
|
149
148
|
</html>
|
|
149
|
+
|
|
150
150
|
```
|
|
151
151
|
|
|
152
152
|
## Html Synxtax
|
|
@@ -13,11 +13,11 @@ Modern.js 生成器会提供一个可交互的问答界面，根据结果初始
|
|
|
13
13
|
[INFO] git 仓库初始化成功
|
|
14
14
|
[INFO] 创建成功！
|
|
15
15
|
可在新项目的目录下运行以下命令：
|
|
16
|
-
pnpm run dev #
|
|
17
|
-
pnpm run build #
|
|
18
|
-
pnpm run serve #
|
|
19
|
-
pnpm run lint #
|
|
20
|
-
pnpm run new #
|
|
16
|
+
pnpm run dev # 启动开发服务器
|
|
17
|
+
pnpm run build # 构建生产环境产物
|
|
18
|
+
pnpm run serve # 启动生产环境服务
|
|
19
|
+
pnpm run lint # 运行 ESLint 并自动修复问题
|
|
20
|
+
pnpm run new # 启用可选功能或创建项目要素
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
:::note
|
|
@@ -27,12 +27,15 @@ export default defineConfig({
|
|
|
27
27
|
|
|
28
28
|
- `mode`：`string = 'string'`，默认为使用 `renderToString` 渲染。配置为 'stream' 开启流式渲染。
|
|
29
29
|
- `forceCSR`：`boolean = false`，默认关闭强制 CSR 渲染。配置为 `true` 后，在页面访问时添加 `?csr=true` 即可强制 CSR。
|
|
30
|
+
- `inlineScript`：`boolean = true`，默认情况下，SSR 的数据会以内联脚本的方式注入到 HTML 中，并且直接赋值给全局变量。配置为 `false` 后，会下发 JSON，而不是赋值给全局变量。
|
|
31
|
+
|
|
30
32
|
|
|
31
33
|
```ts title="modern.config.ts"
|
|
32
34
|
export default defineConfig({
|
|
33
35
|
server: {
|
|
34
36
|
forceCSR: true,
|
|
35
37
|
mode: 'stream',
|
|
38
|
+
inlineScript: false,
|
|
36
39
|
},
|
|
37
40
|
});
|
|
38
41
|
```
|
|
@@ -49,6 +49,8 @@ import { Html, Body, Root, Head, Scripts } from '@modern-js/runtime/document';
|
|
|
49
49
|
|
|
50
50
|
- `Scripts`：构建产生的 script 内容，可用于调整构建产物的位置，默认放在 `<Head>` 组件中。
|
|
51
51
|
|
|
52
|
+
- `Comment`：将用户编写的 `<!-- gateway -->` 这种注释，保留输出到最新渲染的 html 中。
|
|
53
|
+
|
|
52
54
|
### 模板参数
|
|
53
55
|
|
|
54
56
|
因为是 JSX 形式，`Document.[jt]sx` 里，可以比较自由的在组件内使用各种变量去赋值给各种自定义组件。
|
|
@@ -69,8 +71,8 @@ import {
|
|
|
69
71
|
Root,
|
|
70
72
|
Head,
|
|
71
73
|
Body,
|
|
72
|
-
Scripts,
|
|
73
74
|
DocumentContext,
|
|
75
|
+
Comment,
|
|
74
76
|
} from '@modern-js/runtime/document';
|
|
75
77
|
|
|
76
78
|
export default function Document(): React.ReactElement {
|
|
@@ -84,7 +86,8 @@ export default function Document(): React.ReactElement {
|
|
|
84
86
|
return (
|
|
85
87
|
<Html>
|
|
86
88
|
<Head>
|
|
87
|
-
<link href="https://modernjs.dev"
|
|
89
|
+
<link href="https://modernjs.dev" />
|
|
90
|
+
<Comment>{'<!-- Need a Comment -->'}</Comment>
|
|
88
91
|
</Head>
|
|
89
92
|
<Body>
|
|
90
93
|
<Root rootId="root">
|
|
@@ -105,49 +108,43 @@ export default function Document(): React.ReactElement {
|
|
|
105
108
|
```html
|
|
106
109
|
<!DOCTYPE html>
|
|
107
110
|
<html>
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
<meta
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
<meta
|
|
115
|
-
<meta name="
|
|
116
|
-
<meta name="
|
|
117
|
-
<meta name="
|
|
118
|
-
<meta name="
|
|
119
|
-
<
|
|
120
|
-
<script>
|
|
121
|
-
...
|
|
122
|
-
</script>
|
|
111
|
+
|
|
112
|
+
<head>
|
|
113
|
+
<meta charset="utf-8">
|
|
114
|
+
<meta name="viewport"
|
|
115
|
+
content="width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
|
|
116
|
+
<meta http-equiv="x-ua-compatible" content="ie=edge">
|
|
117
|
+
<meta name="renderer" content="webkit">
|
|
118
|
+
<meta name="layoutmode" content="standard">
|
|
119
|
+
<meta name="imagemode" content="force">
|
|
120
|
+
<meta name="wap-font-scale" content="no">
|
|
121
|
+
<meta name="format-detection" content="telephone=no">
|
|
122
|
+
<link rel="icon" href="/a.icon">
|
|
123
|
+
<script defer src="/static/js/builder-runtime.js"></script>
|
|
123
124
|
<script defer src="/static/js/lib-react.js"></script>
|
|
124
125
|
<script defer src="/static/js/lib-polyfill.js"></script>
|
|
125
126
|
<script defer src="/static/js/lib-router.js"></script>
|
|
126
|
-
<script
|
|
127
|
-
defer
|
|
128
|
-
src="/static/js/vendors-node_modules_pnpm_loadable_component_5_15_2_react_18_2_0_node_modules_loadable_compon-3fb0cf.js"
|
|
129
|
-
></script>
|
|
130
|
-
<script
|
|
131
|
-
defer
|
|
132
|
-
src="/static/js/packages_runtime_plugin-router-legacy_dist_js_treeshaking_runtime_index_js-packages_runtime_p-28f4c9.js"
|
|
133
|
-
></script>
|
|
127
|
+
<script xxx>
|
|
134
128
|
<script defer src="/static/js/sub.js"></script>
|
|
135
|
-
<link href="https://
|
|
136
|
-
|
|
129
|
+
<link href="https://modernjs.dev" />
|
|
130
|
+
<!-- Need a Comment -->
|
|
131
|
+
</head>
|
|
137
132
|
|
|
138
|
-
|
|
133
|
+
<body>
|
|
139
134
|
<div id="root">
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
135
|
+
<!--<?- html ?>-->
|
|
136
|
+
<h1 style="color:red">以下为构建时传过来的参数：</h1>
|
|
137
|
+
<h2> entryName：sub</h2>
|
|
138
|
+
<h2> title：</h2>
|
|
139
|
+
<h2> rootId: root</h2>
|
|
145
140
|
</div>
|
|
146
141
|
<h1>bottom</h1>
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
142
|
+
<!--<?- chunksMap.js ?>-->
|
|
143
|
+
<!--<?- SSRDataScript ?>-->
|
|
144
|
+
</body>
|
|
145
|
+
|
|
150
146
|
</html>
|
|
147
|
+
|
|
151
148
|
```
|
|
152
149
|
|
|
153
150
|
## Html 语法
|
|
@@ -169,6 +169,26 @@ export default () => {
|
|
|
169
169
|
|
|
170
170
|
在 loader 中，params 会作为 [loader](/guides/basic-features/data-fetch#loader-函数) 的入参，通过 `params.xxx` 可以获取。
|
|
171
171
|
|
|
172
|
+
### 动态可选路由
|
|
173
|
+
|
|
174
|
+
通过 `[$]` 命名的文件目录，生成的路由会作为动态路由。例如以下文件目录：
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
└── routes
|
|
178
|
+
├── user
|
|
179
|
+
│ └── [id$]
|
|
180
|
+
│ └── page.tsx
|
|
181
|
+
├── blog
|
|
182
|
+
│ └── page.tsx
|
|
183
|
+
└── page.tsx
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`routes/user/[id$]/page.tsx` 文件会转为 `/user/:id?` 路由。`/user` 下的所有路由都会匹配到该路由，并且 `id` 参数可选存在。通常在区分**创建**于**编辑**时，可以使用该路由。
|
|
187
|
+
|
|
188
|
+
在组件中，可以通过 [useParams](/apis/app/runtime/router/router#useparams) 获取对应命名的参数。
|
|
189
|
+
|
|
190
|
+
在 loader 中，params 会作为 [loader](/guides/basic-features/data-fetch#loader-函数) 的入参，通过 `params.xxx` 可以获取。
|
|
191
|
+
|
|
172
192
|
### 通配路由
|
|
173
193
|
|
|
174
194
|
如果在 routes 目录下创建 `$.tsx` 文件，该文件会作为通配路由组件，当没有匹配的路由时，会渲染该路由组件。
|
|
@@ -59,9 +59,9 @@ pnpm run new
|
|
|
59
59
|
[INFO] 依赖自动安装成功
|
|
60
60
|
[INFO] 创建成功！
|
|
61
61
|
可在新项目的目录下运行以下命令：
|
|
62
|
-
pnpm run dev #
|
|
63
|
-
pnpm run build #
|
|
64
|
-
pnpm run serve #
|
|
65
|
-
pnpm run lint #
|
|
66
|
-
pnpm run new #
|
|
62
|
+
pnpm run dev # 启动开发服务器
|
|
63
|
+
pnpm run build # 构建生产环境产物
|
|
64
|
+
pnpm run serve # 启动生产环境服务
|
|
65
|
+
pnpm run lint # 运行 ESLint 并自动修复问题
|
|
66
|
+
pnpm run new # 启用可选功能或创建项目要素
|
|
67
67
|
```
|
package/package.json
CHANGED
|
@@ -11,13 +11,13 @@
|
|
|
11
11
|
"modern",
|
|
12
12
|
"modern.js"
|
|
13
13
|
],
|
|
14
|
-
"version": "2.
|
|
14
|
+
"version": "2.14.0",
|
|
15
15
|
"publishConfig": {
|
|
16
16
|
"registry": "https://registry.npmjs.org/",
|
|
17
17
|
"access": "public"
|
|
18
18
|
},
|
|
19
19
|
"peerDependencies": {
|
|
20
|
-
"@modern-js/builder-doc": "^2.
|
|
20
|
+
"@modern-js/builder-doc": "^2.14.0"
|
|
21
21
|
},
|
|
22
22
|
"devDependencies": {
|
|
23
23
|
"classnames": "^2",
|
|
@@ -29,9 +29,9 @@
|
|
|
29
29
|
"fs-extra": "^10",
|
|
30
30
|
"@types/node": "^16",
|
|
31
31
|
"@types/fs-extra": "^9",
|
|
32
|
-
"@modern-js/builder-doc": "2.
|
|
33
|
-
"@modern-js/doc-tools": "2.
|
|
34
|
-
"@modern-js/doc-plugin-auto-sidebar": "2.
|
|
32
|
+
"@modern-js/builder-doc": "2.14.0",
|
|
33
|
+
"@modern-js/doc-tools": "2.14.0",
|
|
34
|
+
"@modern-js/doc-plugin-auto-sidebar": "2.14.0"
|
|
35
35
|
},
|
|
36
36
|
"scripts": {
|
|
37
37
|
"dev": "modern dev",
|