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.md DELETED Viewed

@@ -1,164 +0,0 @@
----
-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 进程中，例如：
-```env
-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`](/docs/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`](/docs/configure/app/source/define)。

package/zh/guides/basic-features/html.md DELETED Viewed

@@ -1,243 +0,0 @@
----
-title: HTML 模板
-sidebar_position: 9
----
-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](/docs/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](/docs/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/mock.md DELETED Viewed

@@ -1,78 +0,0 @@
----
-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.md DELETED Viewed

@@ -1,59 +0,0 @@
----
-title: 代理
-sidebar_position: 5
----
-## 本地代理
-Modern.js 在 [`tools.devServer`](/docs/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.md'
-<GlobalProxy />
-## BFF 代理
-通过配置 [`bff.proxy`](/docs/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();
-```