npm - @modern-js/main-doc - Versions diffs - 2.1.0 → 2.3.0 - Mend

@modern-js/main-doc 2.1.0 → 2.3.0

Files changed (1299) hide show

package/zh/guides/basic-features/env-vars.mdx ADDED Viewed

@@ -0,0 +1,168 @@
+---
+title: 环境变量
+sidebar_position: 7
+---
+# 环境变量
+Modern.js 提供了对环境变量的支持，包含内置的环境变量和自定义的环境变量。
+## 内置的环境变量
+### NODE_ENV
+表示当前的执行环境，是**只读的**的环境变量，其值在不同的执行命令下具有不同的值：
+- `production`：执行 `modern build`、`modern serve` 命令时的默认值。
+- `test`：执行 `modern test` 命令时的默认值。
+- `development`：执行 `modern dev` 命令时的默认值，同时也是其他所有情况下的默认值。
+### MODERN_ENV
+手动设置当前的执行环境。除了上述 NODE_ENV 对应的值之外，这里支持自定义环境名称，例如 `staging`、`boe` 等。
+:::tip
+MODERN_ENV 的优先级高于 NODE_ENV。
+:::
+### MODERN_TARGET
+使用 `@modern-js/runtime` 时会自动注入，用于区分 SSR 与 CSR 环境。开发者可以自行在代码中判断，构建时会默认移除 dead code。
+```ts title="App.tsx"
+function App() {
+  if (process.env.MODERN_TARGET === 'browser') {
+    console.log(window.innerHeight);
+  }
+}
+```
+开发环境打包后，可以看到 SSR 产物和 CSR 产物如下：
+```js title="dist/bundles/main.js"
+function App() {
+  if (false) {
+  }
+}
+```
+```js title="dist/static/main.js"
+function App() {
+  if (true) {
+    console.log(window.innerHeight);
+  }
+}
+```
+:::note
+在生产环境，会将 dead code 移除，例如上述 `if` 语句。
+:::
+这种方式可以针对不同客户端提供不同的产物，保证代码体积最小化。也能方便处理不同环境下，代码中的一些副作用，
+## 自定义环境变量
+环境变量支持通过 `shell` 和 `.env` 文件两种方式指定。
+### 通过 `shell` 指定
+在命令前添加自定义环境变量：
+```shell
+REACT_APP_FOO=123 BAR=456 pnpm run dev
+```
+### 通过 `.env` 文件指定
+在项目根目录创建 `.env` 文件，并添加自定义环境变量，这些环境变量会默认添加到启动项目的 Node.js 进程中，例如：
+```bash
+REACT_APP_FOO=123
+BAR=456
+```
+`.env` 文件遵循以下规则加载规则：
+- `.env`：默认加载。
+- `.env.{ MODERN_ENV | NODE_ENV }`：针对具体环境设置环境变量，会覆盖 `.env` 中的设置。
+当需要根据环境使用不同的配置时，可以把环境变量定义到对应环境名称的 `.env` 文件中，并在启动项目时手动设置执行环境。例如使用以下命令启动项目时，将会加载 `.env` 和 `.env.staging`:
+```shell
+MODERN_ENV=staging pnpm run dev
+```
+## 使用环境变量
+### 约定命名
+在前端代码中可以直接使用 `NODE_ENV` 环境变量。另外，以 `MODERN_` 开头的自定义环境变量，也可以在代码中直接使用。
+例如:
+```js
+if (process.env.NODE_ENV === 'development') {
+  // do something
+}
+```
+执行 `pnpm run dev` 命令之后可以看到如下构建产物：
+```js
+if (true) {
+  // do something
+}
+```
+同样在自定义的 HTML 模板中，也可以直接使用这类环境变量。如 `config/html/head.html`:
+```js
+<meta name="test" content="<process.env.NODE_ENV>">
+```
+### 任意命名
+如果需要在代码中使用任意名称的环境变量，可以在 [`source.globalVars`](/configure/app/source/global-vars) 配置指定, 例如：
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    globalVars: {
+      'process.env.VERSION': process.env.VERSION,
+    }.
+  },
+});
+```
+此时，在代码中的 `process.env.VERSION`，将会被替换为环境变量中 `VERSION` 的值。
+:::note
+`source.globalVars` 也支持将其他表达式或字符串替换为指定的值，不仅限于环境变量。
+:::
+## 使用全局替换
+除了环境变量，Modern.js 也支持将代码中的变量替换成其它值或者表达式，可以用于在代码逻辑中区分开发环境与生产环境等场景。
+例如将代码中的 `TWO` 转换为 `1 + 1` 的表达式：
+```ts
+export default {
+  source: {
+    define: {
+      TWO: '1 + 1',
+    },
+  },
+};
+```
+```ts
+const foo = TWO;
+// ⬇️ Turn into being...
+const foo = 1 + 1;
+```
+在大多数情况下，`source.globalVars` 已经能满足替换变量的需求。但 `source.globalVars` 传入的值都会默认被 JSON 序列化，因此无法做出像上面例子中 `1 + 1` 的替换，此时就需要使用 [`source.define`](/configure/app/source/define)。

package/zh/guides/basic-features/html.mdx ADDED Viewed

@@ -0,0 +1,247 @@
+---
+title: HTML 模板
+sidebar_position: 9
+---
+# HTML 模板
+Modern.js 提供了 **JSX 语法**和**HTML(Ejs) 语法**两种方式用于自定义 HTML 模板。
+## JSX 语法
+Modern.js 约定，在 `src/` 目录下，或在入口目录下，可以创建 `Document.[jt]sx` 并默认导出组件。该组件的渲染结果可以作为入口的 HTML 模板。
+例如以下目录结构：
+```bash
+.
+├── src
+│   ├── Document.tsx
+│   ├── entry-a
+│   │   ├── Document.tsx
+│   │   └── routes
+│   ├── entry-b
+│   │   └── routes
+│   └── modern-app-env.d.ts
+```
+`entry-a` 会优先使用当前入口下的 `Docoument.[jt]sx` 文件。如果当前入口没有 `Document.[jt]sx` 文件，例如 `entry-b`，则会查找根目录下的 `Document.[jt]sx` 文件。
+如果还没有，则会兜底到传统模板的逻辑。
+### HTML 组件
+Modern.js 提供了一些列渲染页面的组件，用来帮助开发者生成模板，可以从 `@modern-js/runtime/document` 中导出这些组件：
+```tsx
+import { Html, Body, Root, Head, Scripts } from '@modern-js/runtime/document';
+```
+这些组件分别渲染：
+- `Html`：提供原生 HTML Element 的能力，并能默认渲染开发者未添加的必须的组件。`<Head>` 和 `<Body>` 是必须要存在的，其它组件可以按需选择合适的组件进行组装。
+- `Body`：提供原生 Body Element 的能力，内部需要包含 `<Root>` 组件，也支持其它元素同时作为子元素，例如添加页脚。
+- `Root`：渲染的根节点 `<div id='root'></div>`。默认根节点的 `id = 'root'`。可以设置 `props.rootId` 来更改 id 属性。可以添加子组件，也会被渲染到 HTML 模板中，当 React 渲染完成后会被覆盖，一般用来实现全局 Loading。
+- `Head`：提供原生 Head Element 的能力，并会自动填充 `<meta>`，以及 `<Scripts>` 组件。
+- `Scripts`：构建产生的 script 内容，可用于调整构建产物的位置，默认放在 `<Head>` 组件中。
+### 模板参数
+因为是 JSX 形式，`Document.[jt]sx` 里，可以比较自由的在组件内使用各种变量去赋值给各种自定义组件。
+Modern.js 也提供了 `DocumentContext` 来提供一些配置、环境参数，方便直接获取。主要以下参数：
+- `processEnv`：提供构建时的 `process.env`
+- `config`：Modern.js 项目的配置。目前只暴露出 output 相关的配置
+- `entryName`：当前的入口名
+- `templateParams`：HTML 模板的参数（为了兼容传统模板，不推荐使用）
+### 示例
+```tsx
+import React, { useContext } from 'react';
+import {
+  Html,
+  Root,
+  Head,
+  Body,
+  Scripts,
+  DocumentContext,
+} from '@modern-js/runtime/document';
+export default function Document(): React.ReactElement {
+  // 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' }}>以下为构建时传过来的参数：</h1>
+          <h2> entryName：{entryName}</h2>
+          <h2> title：{htmlConfig.title}</h2>
+          <h2> rootId: {templateParams.mountId}</h2>
+        </Root>
+        <h1>bottom</h1>
+      </Body>
+    </Html>
+  );
+}
+```
+以上 JSX 组件，将会生成以下 HTML 模板：
+```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">以下为构建时传过来的参数：</h1>
+      <h2>entryName：sub</h2>
+      <h2>title：</h2>
+      <h2>rootId: root</h2>
+    </div>
+    <h1>bottom</h1>
+    {/* <?- chunksMap.js ?> */}
+    {/* <?- SSRDataScript ?> */}
+  </body>
+</html>
+```
+## Html 语法
+Modern.js 也支持 HTML 语法。默认情况下，Modern.js 的应用工程中会内置一份 HTML 模板，用于生成 HTML 代码。
+基于 HTML 语法的模板，Modern.js 提供了 **自定义 HTML 片段**和**完全自定义 HTML 模板**两种方式来自定义模板。
+### 自定义 HTML 片段
+在应用根目录下，创建 `config/html/` 目录，该目录下支持创建四种 HTML 片段。
+- `top.html`
+- `head.html`
+- `body.html`
+- `bottom.html`
+**这些片段将按位置注入到默认的 HTML 模板中。**
+```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>
+```
+代码片段支持使用 [Lodash template](https://lodash.com/docs/4.17.15#template) 语法。
+例如在 `body.html` 里插入一个外链脚本：
+```html title="config/html/body.html"
+<script src="//example.com/assets/a.js"></script>
+```
+:::info
+自定义 HTML 片段的实现方式是将片段与框架内置的模板进行合并，由于框架的默认模板中已经存在 `<title>`，因此自定义 HTML 模板中的 title 标签无法生效，请通过 [html.title](/configure/app/html/title) 来修改页面标题。
+:::
+### 完全自定义 HTML 模板
+某些情况下，HTML 片段无法满足自定义需求，Modern.js 提供了完全自定义方式。
+:::caution 注意
+通常不建议直接覆盖默认的 HTML 模板，可能会失去一部分功能选项。即使需要替换，建议以内置模板为基础，按需修改。
+:::
+在 `config/html/` 目录下，创建 `index.html` 文件,该文件将替代默认的 HTML 模板。
+:::info
+内部默认 HTML 模板可以在 `node_modules/.modern-js/${entryName}/index.html` 中查看。
+:::
+### 模板参数
+模板中使用的参数可以通过 [html.templateParameters](/configure/app/html/template-parameters) 配置项来定义。
+### 按入口设置
+`config/html/` 目录中的 HTML 片段对应用中的所有入口都生效。如果希望按入口自定义 HTML 片段，可以在 `config/html/` 目录下新建一个以**入口名**命名的目录，然后在这个目录中自定义 HTML 片段。
+例如，如下设置的 HTML 片段仅对入口 `entry1` 生效：
+```bash
+.
+├── config/
+│   └── html/
+│       └── entry1
+│           ├── head.html
+│           └── body.html
+└── src/
+    ├── entry1/
+    │   └── routes
+    └── entry2/
+        └── routes
+```

package/zh/guides/basic-features/{index.md → index.mdx} RENAMED Viewed

File without changes

package/zh/guides/basic-features/mock.mdx ADDED Viewed

@@ -0,0 +1,79 @@
+---
+title: 数据模拟
+sidebar_position: 6
+---
+# 数据模拟
+Modern.js 提供了快速生成 Mock 数据的功能，能够让前端独立自主开发，不被后端接口阻塞。
+## Mock 文件
+约定当 `config/mock` 目录下存在 `index.[jt]s` 时，会自动开启 Mock 功能，如下：
+```bash
+.
+├── config
+│   └── mock
+│       └── index.ts
+├── src
+│   └── App.tsx
+└── modern.config.ts
+```
+## 编写 Mock 文件
+`config/mock/index.ts` 文件只需要导出一个包含所有 Mock API 的对象，对象的属性由请求配置 `method` 和 `url` 组成，对应的属性值可以为 `Object`、`Array`、`Function`：
+```js
+module.exports = {
+  /* 属性为具体的 method 和 请求 url，值为 object 或 array 作为请求的结果 */
+  'GET /api/getInfo': { data: [1, 2, 3, 4] },
+  /* method 默认为 GET */
+  '/api/getExample': { id: 1 },
+  /* 可以使用自定义函数根据请求动态返回数据，返回值参考 express middleware */
+  'POST /api/addInfo': (req, res, next) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.end('200');
+  },
+};
+```
+代码中访问 `http://localhost:8080/api/getInfo` 时，接口会返回 JSON 格式数据：`{ "data": [1, 2, 3, 4] }`。
+## 返回随机数据
+可以在 `config/mock/index.js` 中自主引入 [Mock.js](https://github.com/nuysoft/Mock/wiki/Getting-Started) 等库生成随机数据，例如：
+```js
+const Mock = require('mockjs');
+module.exports = {
+  '/api/getInfo': Mock.mock({
+    'data|1-10': [{ name: '@cname' }],
+  }) /* => {data: [{name: "董霞"}, {name: "魏敏"},  {name: "石磊"}} */,
+};
+```
+:::info 更多随机数据生成库
+- [Chancejs](https://github.com/chancejs/chancejs)
+- [Mock](https://github.com/nuysoft/Mock/wiki/Getting-Started)
+:::
+## 延迟返回
+- 可以使用浏览器「 弱网模拟 」的功能实现。
+- 可以通过 `setTimeout` 为单个接口设置延迟，例如：
+```js
+module.exports = {
+  'api/getInfo': (req, res) => {
+    setTimeout(() => {
+      res.end('delay 2000ms');
+    }, 2000);
+  },
+};
+```

package/zh/guides/basic-features/proxy.mdx ADDED Viewed

@@ -0,0 +1,61 @@
+---
+title: 代理
+sidebar_position: 5
+---
+# 代理
+## 本地代理
+Modern.js 在 [`tools.devServer`](/configure/app/tools/dev-server) 中提供了配置开发环境代理的方式。例如，将本地开发接口，代理到线上某个地址：
+```ts 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,
+        },
+      },
+    },
+  },
+});
+```
+请求 `http://localhost:8080/go/api` 时，会从 [http://www.example.com/](http://www.example.com/) 返回响应内容。
+:::info 补充信息
+配置格式可参考：[http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)。
+:::
+## 全局代理
+import GlobalProxy from "@site-docs/components/global-proxy"
+<GlobalProxy />
+## BFF 代理
+通过配置 [`bff.proxy`](/configure/app/bff/proxy) 可以代理 BFF API 请求到指定的服务上，上述两种代理不同，它同样可以用在生产环境：
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    proxy: {
+      '/api/v1': 'https://cnodejs.org',
+    },
+  },
+});
+```
+例如代码中使用一体化 BFF 调用时，最终请求 `http://localhost:8080/api/v1/topics` 会自动代理到 `https://cnodejs.org/api/v1/topics`：
+```js
+import getTopics from '@api/v1/topics';
+getTopics();
+```