npm - @modern-js/main-doc - Versions diffs - 2.0.0-beta.6 → 2.0.0-canary.0 - Mend

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

Files changed (58) hide show

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/html.md ADDED Viewed

@@ -0,0 +1,235 @@
+---
+title: HTML Template
+sidebar_position: 9
+---
+Modern.js provides **JSX syntax**  and **HTML(Ejs) syntax** for customizing HTML template.
+## JSX syntax
+Modern.js convention, in the `src/`, or in the entry directory, you can create `Document.[jt]sx` and export a component by default. The rendering result of this component can be used as an HTML template for the entry.
+For example the following directory structure:
+```bash
+.
+├── src
+│   ├── Document.tsx
+│   ├── entry-a
+│   │   ├── Document.tsx
+│   │   └── routes
+│   ├── entry-b
+│   │   └── routes
+│   └── modern-app-env.d.ts
+```
+`entry-a` will take precedence over the `Docoument.[jt]sx` file under the current entry. If the current entry does not have a `Document.[jt]sx` file, such as `entry-b`, it will look for the `Document.[jt]sx` file in the root directory.
+If not, it will go to the the logic of traditional templates.
+### HTML Component
+Modern.js provides a list of components for rendering pages to help developers generate templates, which can be exported from `@modern-js/runtime/document`:
+```tsx
+import { Html, Body, Root, Head, Scripts } from '@modern-js/runtime/document';
+```
+These components are rendered:
+- `Html`：Provide the ability of native HTML Elements, and render necessary components that the developer did not add by default. `<Head>` and `<Body>` must exist, and other components can be assembled by selecting appropriate components on demand.
+- `Body`：Provide the ability of native Body Element, which needs to contain the `<Root>` component internally, and also supports other elements as child elements at the same time, such as adding footers.
+- `Root`：React root element `<div id='root'></div>`。the default element id is `id = 'root'`, can set `props.rootId` to change the id。Child components can be added, and will also be rendered into HTML templates, which will be overwritten when React rendering is complete, generally used to implement global Loading.
+- `Head`：Provides native Head Element capabilities and automatically populates `<meta>`, as well as the `<Scripts>` component.
+- `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.
+### Template Params
+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.
+At the same time, Modern.js provides `DocumentContext` to provide some configuration and environment parameters, The main parameters as follow:
+- `processEnv`：Provide build-time env vars.
+- `config`：The configuration of the project, only `output` are exposed.
+- `entryName`：current entry name.
+- `templateParams`：HTML template params(in order to be compatible with traditional templates, it is not recommended to use).
+### Examples
+```tsx
+import React, { useContext } from 'react';
+import {
+  Html,
+  Root,
+  Head,
+  Body,
+  Scripts,
+  DocumentContext
+} from '@modern-js/runtime/document';
+export default function Document(): React.ReactElement {
+  // the params provide by DocumentContext
+  const {
+    config: { output: htmlConfig },
+    entryName,
+    templateParams,
+  } = useContext(DocumentContext);
+  return (
+    <Html>
+      <Head>
+        <link href="https://modernjs.dev">Modern.js</link>
+      </Head>
+      <Body>
+        <Root rootId="root">
+          <h1 style={{ color: 'red' }}>Some Params：</h1>
+          <h2> entryName：{entryName}</h2>
+          <h2> title：{htmlConfig.title}</h2>
+          <h2> rootId: {templateParams.mountId}</h2>
+        </Root>
+        <h1>bottom</h1>
+      </Body>
+    </Html>
+  );
+}
+```
+The above JSX component will generate the following HTML template:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport"
+        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">
+    <meta http-equiv="x-ua-compatible" content="ie=edge">
+    <meta name="renderer" content="webkit">
+    <meta name="layoutmode" content="standard">
+    <meta name="imagemode" content="force">
+    <meta name="wap-font-scale" content="no">
+    <meta name="format-detection" content="telephone=no">
+    <script>...</script>
+    <script defer src="/static/js/lib-react.js"></script>
+    <script defer src="/static/js/lib-polyfill.js"></script>
+    <script defer src="/static/js/lib-router.js"></script>
+    <script defer
+        src="/static/js/vendors-node_modules_pnpm_loadable_component_5_15_2_react_18_2_0_node_modules_loadable_compon-3fb0cf.js"></script>
+    <script defer
+        src="/static/js/packages_runtime_plugin-router-legacy_dist_js_treeshaking_runtime_index_js-packages_runtime_p-28f4c9.js"></script>
+    <script defer src="/static/js/sub.js"></script>
+    <link href="https://www.baidu.com" />
+</head>
+<body>
+    <div id="root">
+        <!--<?- html ?>-->
+        <h1 style="color:red">Some Params：</h1>
+        <h2> entryName：sub</h2>
+        <h2> title：</h2>
+        <h2> rootId: root</h2>
+    </div>
+    <h1>bottom</h1>
+    <!--<?- chunksMap.js ?>-->
+    <!--<?- SSRDataScript ?>-->
+</body>
+</html>
+```
+## Html Synxtax
+Modern.js also supports HTML syntax. By default, an HTML template is built into the Modern.js application project to generate HTML code.
+Based on HTML syntax templates, Modern.js provides **Custom HTML Fragments** and **Fully Custom HTML Templates** two ways to customize templates.
+### Custom HTML Fragments
+In the application root directory, create the `config/html/` directory, which supports the creation of four kinds of HTML fragments.
+- `top.html`
+- `head.html`
+- `body.html`
+- `bottom.html`
+**These fragments will be injected into the default HTML template.**
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <%= meta %>
+  <title><%= title %></title>
+  <%= topTemplate %>
+  <script>
+    window.__assetPrefix__ = '<%= assetPrefix %>';
+  </script>
+  <%= headTemplate %>
+  <!-- webpack inject css -->
+</head>
+<body>
+  <noscript>
+    We're sorry but react app doesn't work properly without JavaScript enabled. Please enable it to continue.
+  </noscript>
+  <div id="<%= mountId %>"></div>
+  <%= bodyTemplate %>
+  <!-- webpack inject js -->
+  <!--<?- bottomTemplate ?>-->
+</body>
+</html>
+```
+HTML Fragments support the use [Lodash template](https://lodash.com/docs/4.17.15#template)。
+For example, insert a script in `body.html`:
+```html title="config/html/body.html"
+<script src="//example.com/assets/a.js"></script>
+```
+:::info
+The implementation of the custom HTML fragment is to merge the fragment with the built-in template of the frame. Since `<title>` already exists in the default template of the frame, the `<title>` in the custom HTML template cannot take effect. Please pass [html.title](/docs/configure/app/html/title) to modify the page title.
+:::
+### Fully Custom HTML Templates
+In some cases, HTML snippets do not meet the customization requirements, Modern.js provide a fully customized way.
+:::caution
+It is not recommended to override the default HTML template directly, and some features may be lost. Even if it needs to be replaced, it is recommended to build on the built-in template and modify it as needed.
+:::
+In the `config/html/` directory, create a index.html file that will override the default HTML template.
+:::info
+The internal default HTML template can be viewed in `node_modules/.modern-js/${entryName}/index.html`.
+:::
+### Template Params
+The parameters used in the template can be defined by the [html.templateParameters](/docs/configure/app/html/template-parameters).
+### Config By Entry
+The fragment in the `config/html/` directory are valid for all entries in the application. If you want to customize the HTML by entry, you can create a new directory named with the **entry name** in the `config/html/` directory, and then customize the HTML snippets in this directory.
+For example, the following HTML fragment is only valid for `entry1`:
+```html
+.
+├── config/
+│   └── html/
+│       └── entry1
+│           ├── head.html
+│           └── body.html
+└── src/
+    ├── entry1/
+    │   └── routes
+    └── entry2/
+        └── routes
+```

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/mock.md ADDED Viewed

@@ -0,0 +1,78 @@
+---
+title: Mock
+sidebar_position: 6
+---
+Modern.js provides the ability to quickly generate Mock data, allowing the front-end to develop independently without being blocked by the back-end interface.
+## Mock File
+By convention, when there is `index.[jt]s` in the `config/mock/` directory, the Mock Data will be automatically enabled, as follows:
+```bash
+.
+├── config
+│   └── mock
+│       └── index.ts
+├── src
+│   └── App.tsx
+└── modern.config.ts
+```
+## Writing Mock Files
+the `config/mock/index.ts` file only needs to export an object containing all Mock APIs. The properties of the object are composed of the request configuration `method` and `url`, and the corresponding property values can be `Object`, `Array`, `Function`:
+```js
+export default {
+  /* The attribute is the concrete method and request url, and the value is object or array as the result of the request */
+  'GET /api/getInfo': { data: [1, 2, 3, 4] },
+  /* the default method is GET */
+  '/api/getExample': { id: 1 },
+  /* You can use custom functions to dynamically return data */
+  'POST /api/addInfo': (req, res, next) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.end('200');
+  },
+};
+```
+when access `http://localhost:8080/api/getInfo`, the api will return json `{ "data": [1, 2, 3, 4] }`。
+## Return Random Data
+Libraries such as [Mock.js](https://github.com/nuysoft/Mock/wiki/Getting-Started) can be used in `config/mock/index.js` to generate random data, for example:
+```js
+const Mock = require('mockjs');
+module.exports = {
+  '/api/getInfo': Mock.mock({
+     'data|1-10': [{ name: '@cname' }]
+   }), /* => {data: [{name: "董霞"}, {name: "魏敏"},  {name: "石磊"}} */
+};
+```
+:::info Other Mock Lib
+* [Chancejs](https://github.com/chancejs/chancejs)
+* [Mock](https://github.com/nuysoft/Mock/wiki/Getting-Started)
+:::
+## Delayed Return
+- It can be achieved using the function of the browser "weak connection simulation".
+- Delays can be set via `setTimeout`, for example:
+```ts
+export default {
+  'api/getInfo': (req, res) => {
+    setTimeout(() => {
+      res.end('delay 2000ms');
+    }, 2000);
+  },
+};
+```

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/proxy.md ADDED Viewed

@@ -0,0 +1,60 @@
+---
+title: Proxy
+sidebar_position: 5
+---
+## Local Proxy
+Modern.js provides a way to configure the development proxy in ['tools.devServer'] (/docs/configure/app/tools/dev-server). For example, to proxy the local interface to an online address:
+```typescript title="modern.config.ts"
+import { defineConfig }  from '@modern-js/app-tools';
+export default defineConfig({
+  tools: {
+    devServer: {
+      proxy: {
+        '/go/api': {
+          target: 'http://www.example.com/',
+          changeOrigin: true,
+        },
+      },
+    },
+  },
+});
+```
+when access `http://localhost:8080/go/api`, the response content is returned from [http://www.example.com/](http://www.example.com/).
+:::info
+For more detail, see [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)。
+:::
+## Global Proxy
+import GlobalProxy from '@site-docs-en/components/global-proxy.md'
+<GlobalProxy />
+## BFF Proxy
+By configuring [`bff.proxy`](/docs/configure/app/bff/proxy), you can proxy BFF API requests to specified services. Unlike other proxy above, it can also be used in the production environment:
+```typescript title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    proxy: {
+      '/api/v1': 'https://cnodejs.org',
+    },
+  },
+});
+```
+For example, when a BFF call is used in the code, the final request `http://localhost:8080/api/v1/topics` will auto proxy to `https://cnodejs.org/api/v1/topics`：
+```js
+import getTopics from '@api/v1/topics'
+getTopics();
+```

package/en/docusaurus-plugin-content-docs/current/guides/get-started/quick-start.md CHANGED Viewed

@@ -61,8 +61,7 @@ info    Starting dev server...
 info    App running at:
   > Local:    http://localhost:8080/
-  > Network:  http://10.94.58.87:8080/
-  > Network:  http://10.254.68.105:8080/
+  > Network:  http://192.168.0.1:8080/
  Client ✔ done in 76.10ms
 ```
@@ -151,8 +150,7 @@ Starting the modern server...
 info    App running at:
   > Local:    http://localhost:8080/
-  > Network:  http://10.94.58.87:8080/
-  > Network:  http://10.254.68.105:8080/
+  > Network:  http://192.168.0.1:8080/
 ```
 Open http://localhost:8000/ in the browser and the content should be the same as when `pnpm run dev`.

package/package.json CHANGED Viewed

@@ -11,7 +11,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.0.0-beta.6",
+  "version": "2.0.0-canary.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -20,11 +20,11 @@
     "@modern-js/builder-doc": "2.0.0-beta.6"
   },
   "devDependencies": {
+    "@modern-js/builder-doc": "2.0.0-beta.6",
     "ts-node": "^10",
     "fs-extra": "^10",
     "@types/node": "^16",
-    "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.0.0-beta.6"
+    "@types/fs-extra": "^9"
   },
   "scripts": {
     "build": "npx ts-node ./scripts/sync.ts"

package/zh/apis/app/hooks/src/index_.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 title: index.[tj]s
-sidebar_position: 3
+sidebar_position: 4
 ---
 应用项目自定义路由入口标识。

package/zh/apis/app/hooks/src/pages.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 title: pages/
-sidebar_position: 2
+sidebar_position: 3
 ---
 应用使用基于文件系统路由时的入口标识。

package/zh/apis/app/hooks/src/routes.md ADDED Viewed

@@ -0,0 +1,89 @@
+---
+title: routes/
+sidebar_position: 2
+---
+应用使用基于文件系统路由时的入口标识。
+当项目结构为 `Routes 入口` 类型时， 会分析 `src/routes` 目录下的文件得到客户端路由配置。具体用法请查看[约定式路由](/docs/guides/basic-features/routes)
+任何在 `src/routes` 下的 `layout.[tj]sx` 和 `page.[tj]sx` 都会作为应用的路由：
+```bash {3}
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+## 基本示例
+`routes` 目录下的目录名会作为路由 url 的映射，其中 `layout.tsx` 中作为布局组件，`page.tsx` 作为内容组件，是整条路由的叶子节点，例如以下目录结构：
+```bash
+.
+└── routes
+    ├── page.tsx
+    └── user
+        └── page.tsx
+```
+会产出下面两条路由：
+- `/`
+- `/user`
+## 动态路由
+如果路由文件的目录名以 `[]` 命名，生成的路由会作为动态路由。例如以下文件目录：
+```
+└── routes
+    ├── [id]
+    │   └── page.tsx
+    ├── blog
+    │   └── page.tsx
+    └── page.tsx
+```
+`routes/[id]/page.tsx` 文件会转为 `/:id` 路由。除了可以确切匹配的 `/blog` 路由，其他所有 `/xxx` 都会匹配到该路由。
+在组件中，可以通过 [useParams](/docs/apis/app/runtime/router/#useparams) 获取对应命名的参数。
+在 loader 中，params 会作为 [loader](/docs/guides/basic-features/data-fetch#loader-函数) 的入参，通过 `params` 的属性可以获取到对应的参数。
+## 布局组件
+如下面的例子，可以通过添加 `layout.tsx`，为所有路由组件添加公共的布局组件：
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+在布局组件中可以通过使用 `<Outlet>` 表示子组件：
+```tsx title=routes/layout.tsx
+import { Link, Outlet, useLoaderData } from '@modern-js/runtime/router';
+export default () => {
+  return (
+    <>
+      <Outlet></Outlet>
+    </>
+  )
+}
+```
+:::note
+`<Outlet>` 是 React Router 6 中新的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+:::

package/zh/components/debug-app.md CHANGED Viewed

@@ -9,8 +9,7 @@ info    Starting dev server...
 info    App running at:
   > Local:    http://localhost:8080/
-  > Network:  http://10.94.58.87:8080/
-  > Network:  http://10.254.68.105:8080/
+  > Network:  http://192.168.0.1:8080/
  Client ✔ done in 76.10ms
 ```

package/zh/components/global-proxy-config.md ADDED Viewed

@@ -0,0 +1,70 @@
+* 类型： `string | Object`
+* 默认值： `null`
+配置该选项后，开发环境时会启动全局代理，类似 [Fiddler](https://www.telerik.com/fiddler), [Charles](https://www.charlesproxy.com/) 等 web 代理调试工具，可以用来查看、修改 HTTP/HTTPS 请求、响应、也可以用作代理服务器。
+:::tip 提示
+使用该选项需要提前安装 `@modern-js/plugin-proxy`。
+:::
+值为 `Object` 时，对象的 `key` 对应匹配的 `pattern`，对象的 `value` 对应匹配的 `target`。
+例如：
+```typescript title="modern.config.ts"
+export default defineConfig({
+  dev: {
+    proxy: {
+      'https://www.baidu.com': 'https://google.com.hk',
+      //可以通过 file 协议直接返回静态文件。
+      'https://example.com/api': 'file://./data.json',
+    }
+  }
+});
+```
+值为 `string` 时， 可以用来指定单独的代理文件，例如：
+```typescript title="modern.config.ts"
+export default defineConfig({
+  dev: {
+    proxy: './proxy.js',
+  },
+});
+```
+```js title="proxy.js"
+module.exports = {
+  name: 'my-app',
+  rules: `
+    ^example.com:8080/api/***   http://localhost:3001/api/$
+  `,
+};
+```
+:::info 注
+Modern.js 全局代理实现底层基于 [whistle](https://wproxy.org/whistle/), 更多匹配模式请参考: [匹配模式](https://wproxy.org/whistle/pattern.html)
+:::
+执行 `dev`, 提示如下时，即代理服务器启动成功：
+```bash
+  App running at:
+  Local:    http://localhost:8080/
+  Network:  http://192.168.0.1:8080/
+ℹ  info      Starting the proxy server.....
+✔  success   Proxy Server start on localhost:8899
+```
+访问 `localhost:8899`, 可以在 UI 界面上查看 Network 以及配置代理规则：
+![proxy ui 界面](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/dev-proxy.png)
+:::caution 注意
+https 代理自动安装证书需要获取 root 权限, 请根据提示输入密码即可。**密码仅在信任证书时使用，不会泄漏或者用于其他环节**。
+:::

package/zh/configure/app/dev/proxy.md CHANGED Viewed

@@ -5,74 +5,6 @@ sidebar_label: proxy
 # dev.proxy
+import GlobalProxyConfig from '@site-docs/components/global-proxy-config.md'
-* 类型： `string | Object`
-* 默认值： `null`
-配置该选项后，开发环境时会启动全局代理，类似 [Fiddler](https://www.telerik.com/fiddler), [Charles](https://www.charlesproxy.com/) 等 web 代理调试工具，可以用来查看、修改 HTTP/HTTPS 请求、响应、也可以用作代理服务器。
-:::tip 提示
-使用该选项需要提前安装 `@modern-js/plugin-proxy`。
-:::
-值为 `Object` 时，对象的 `key` 对应匹配的 `pattern`，对象的 `value` 对应匹配的 `target`。
-例如：
-```typescript title="modern.config.ts"
-export default defineConfig({
-  dev: {
-    proxy: {
-      'https://www.baidu.com': 'https://google.com.hk',
-      //可以通过 file 协议直接返回静态文件。
-      'https://example.com/api': 'file://./data.json',
-    }
-  }
-});
-```
-值为 `string` 时， 可以用来指定单独的代理文件，例如：
-```typescript title="modern.config.ts"
-export default defineConfig({
-  dev: {
-    proxy: './proxy.js',
-  },
-});
-```
-```js title="proxy.js"
-module.exports = {
-  name: 'my-app',
-  rules: `
-    ^example.com:8080/api/***   http://localhost:3001/api/$
-  `,
-};
-```
-:::info 注
-Modern.js 全局代理实现底层基于 [whistle](https://wproxy.org/whistle/), 更多匹配模式请参考: [匹配模式](https://wproxy.org/whistle/pattern.html)
-:::
-执行 `dev`, 提示如下时，即代理服务器启动成功：
-```bash
-  App running at:
-  Local:    http://localhost:8080/
-  Network:  http://192.168.0.1:8080/
-ℹ  info      Starting the proxy server.....
-✔  success   Proxy Server start on localhost:8899
-```
-访问 `localhost:8899`, 可以在 UI 界面上查看 Network 以及配置代理规则：
-![proxy ui 界面](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/dev-proxy.png)
-:::caution 注意
-https 代理自动安装证书需要获取 root 权限, 请根据提示输入密码即可。**密码仅在信任证书时使用，不会泄漏或者用于其他环节**。
-:::
+<GlobalProxyConfig />