@modern-js/main-doc 2.13.4 → 2.14.0
Sign up to get free protection for your applications and to get access to all the features.
- package/CHANGELOG.md +17 -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,22 @@
|
|
|
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
|
+
|
|
3
20
|
## 2.13.4
|
|
4
21
|
|
|
5
22
|
### 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",
|