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

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

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.

Files changed (61) 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.1",
   "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/enable-bff.md ADDED Viewed

@@ -0,0 +1,36 @@
+1. 执行 `pnpm new`，选择启用 BFF
+2. 根据选择的运行时框架，将下面的代码添加到 `modern.config.[tj]s` 中：
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+<Tabs>
+  <TabItem value="express" label="Express.js" default>
+```ts title="edenx.config.ts"
+import ExpressPlugin from '@edenx/plugin-express';
+import BffPlugin from '@edenx/plugin-bff';
+export default defineConfig({
+  plugins: [
+    ExpressPlugin(),
+    BffPlugin()
+  ]
+})
+```
+  </TabItem>
+  <TabItem value="koa" label="Koa.js">
+```ts title="edenx.config.ts"
+import KoaPlugin from '@edenx/plugin-koa';
+import BffPlugin from '@edenx/plugin-bff';
+export default defineConfig({
+  plugins: [
+    KoaPlugin(),
+    BffPlugin()
+  ]
+})
+```
+  </TabItem>
+</Tabs>

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 权限, 请根据提示输入密码即可。**密码仅在信任证书时使用，不会泄漏或者用于其他环节**。
+:::