@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/zh/guides/basic-features/env-vars.mdx

@@ -0,0 +1,180 @@
+---
+sidebar_position: 7
+---
+
+# 环境变量
+
+Modern.js 提供了对环境变量的支持，包含内置的环境变量和自定义的环境变量。
+
+## 内置的环境变量
+
+### ASSET_PREFIX
+
+表示当前资源文件的路径前缀，是**只读的**的环境变量。
+
+### NODE_ENV
+
+表示当前的执行环境，是**只读的**的环境变量，其值在不同的执行命令下具有不同的值：
+
+- `production`：执行 `modern build`、`modern serve` 命令时的默认值。
+- `development`：执行 `modern dev` 命令时的默认值，同时也是其他所有情况下的默认值。
+
+### MODERN_ENV
+
+手动设置当前的执行环境。除了上述 NODE_ENV 对应的值之外，这里支持自定义环境名称，例如 `staging`、`boe` 等。
+
+:::tip
+MODERN_ENV 的优先级高于 NODE_ENV。
+
+:::
+
+### MODERN_TARGET
+
+使用 `@modern-js/runtime` 时，Modern.js 会自动注入 `MODERN_TARGET`，用于区分 SSR 与 CSR 环境。
+
+你可以在代码中通过 `process.env.MODERN_TARGET` 来判断环境，并执行相应的逻辑。
+
+```ts title="App.tsx"
+function App() {
+  if (process.env.MODERN_TARGET === 'browser') {
+    console.log(window.innerHeight);
+  }
+}
+```
+
+在开发环境构建完成后，可以看到 SSR 产物和 CSR 产物如下：
+
+```js title="dist/bundles/main.js"
+// SSR 产物
+function App() {
+  if (false) {
+  }
+}
+```
+
+```js title="dist/static/main.js"
+// CSR 产物
+function App() {
+  if (true) {
+    console.log(window.innerHeight);
+  }
+}
+```
+
+这种方式可以针对不同客户端提供不同的产物，保证代码体积最小化，也便于处理不同环境下代码中的一些副作用。
+
+:::note 死代码移除
+在生产环境，Terser 和 SWC 等代码压缩工具会分析代码，并将 dead code 移除，从而减少产物体积，这个过程被称为死代码移除（DCE）。
+
+例如，上述 `if (false)` 语句包含的代码会被移除，而 `if (true)` 包含的代码将被保留。
+
+如果你未按照上述写法来使用 `process.env.MODERN_TARGET`，代码压缩工具可能会无法分析出 dead code，从而导致产物体积增大。
+
+:::
+
+
+## 自定义环境变量
+
+环境变量支持通过 `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/docs/zh/guides/basic-features/html.mdx

@@ -0,0 +1,262 @@
+---
+title: HTML 模板
+sidebar_position: 9
+---
+
+# HTML 模板
+
+Modern.js 提供了 **JSX 语法**和 **HTML(EJS) 语法**两种方式用于自定义 HTML 模板。
+
+## JSX 语法
+
+Modern.js 约定，在 `src/` 或入口目录下，可以创建 `Document.tsx` 文件并默认导出组件，该组件的渲染结果可以作为入口的 HTML 模板。
+
+例如以下目录结构：
+
+```bash
+.
+└── src
+    ├── Document.tsx
+    ├── entry-a
+    │   ├── Document.tsx
+    │   └── routes
+    ├── entry-b
+    │    └── routes
+    └── modern-app-env.d.ts
+```
+
+`entry-a` 会优先使用当前入口下的 `Document.tsx` 文件。如果当前入口没有 `Document.tsx` 文件，例如 `entry-b`，则会查找根目录下的 `Document.tsx` 文件。
+
+如果未找到，将会使用 Modern.js 的默认模板。
+
+:::tip
+`Document.tsx` 会在构建时由 Modern.js 的 Document 插件创建 Rspack 子编译器流程，编译为面向 Node.js 的产物，并在编译时以 `renderToStaticMarkup` 渲染为字符串作为 HTML 模板内容，其行为类似[静态站点生成](/guides/basic-features/render/ssg.html)。HTML 模板模块不会经过页面 Bundler 的常规编译打包，因此组件中的 React Hooks 不会在浏览器运行时被执行，也不支持导入 JavaScript 以外的图片等资源模块。
+:::
+
+### 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>` 组件中。
+
+- `Comment`：将用户编写的 `<!-- gateway -->` 这种注释，保留输出到最新渲染的 html 中。
+
+### 模板参数
+
+因为是 JSX 形式，`Document.tsx` 里，可以比较自由的在组件内使用各种变量去赋值给各种自定义组件。
+
+Modern.js 也提供了 `DocumentContext` 来提供一些配置、环境参数，方便直接获取。主要以下参数：
+
+- `processEnv`：提供构建时的 `process.env`。
+- `config`：Modern.js 项目的配置。目前只暴露出 output 相关的配置。
+- `entryName`：当前的入口名。
+- `templateParams`：HTML 模板的参数（为了兼容传统模板，不推荐使用）。
+
+### 基础示例
+
+```tsx
+import React, { useContext } from 'react';
+import {
+  Html,
+  Root,
+  Head,
+  Body,
+  Comment,
+  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" />
+        <Comment>{'<!-- Need a Comment -->'}</Comment>
+      </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" />
+    <link rel="icon" href="/a.icon" />
+    <script defer src="/static/js/builder-runtime.js"></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/sub.js"></script>
+    <link href="https://modernjs.dev" />
+    <!-- Need a Comment -->
+  </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>
+```
+
+### Scripts 组件示例
+
+你可以使用 `<Scripts>` 组件，将构建生成的 `<script>` 标签插入到 `<body>` 标签内：
+
+```tsx
+import React from 'react';
+import { Html, Root, Head, Body, Scripts } from '@modern-js/runtime/document';
+
+export default function Document(): React.ReactElement {
+  return (
+    <Html>
+      <Head></Head>
+      <Body>
+        <Root rootId="root"></Root>
+        <Scripts />
+      </Body>
+    </Html>
+  );
+}
+```
+
+## HTML 语法
+
+Modern.js 也支持通过 HTML(EJS) 语法来生成 HTML 文件。
+
+默认情况下，Modern.js 的工程中会内置一份 HTML 模板，用于生成 HTML 代码。如果你需要自定义 HTML 模板，可以使用**自定义 HTML 片段**和**完全自定义 HTML 模板**两种方式。
+
+### 自定义 HTML 片段
+
+在应用根目录下，创建 `config/html/` 目录，该目录下支持创建四种 HTML 片段。
+
+- `top.html`
+- `head.html`
+- `body.html`
+- `bottom.html`
+
+**这些片段将按位置注入到默认的 HTML 模板中。**
+
+```xml
+<!DOCTYPE html>
+<html>
+  <head>
+    <%= topTemplate %>
+    <%= headTemplate %>
+    {/* rspack 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 %>
+    {/* rspack 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/docs/zh/guides/basic-features/output-files.mdx

@@ -0,0 +1,145 @@
+---
+sidebar_position: 10
+---
+
+# 构建产物目录
+
+本章节主要介绍构建产物的目录结构，以及如何控制不同类型产物的输出目录。
+
+## 默认产物目录
+
+下面是最基础的产物目录结构，默认情况下，构建产物会生成在当前项目的 `dist` 目录下。
+
+```bash
+dist
+├── static
+│   ├── css
+│   │   ├── [name].[hash].css
+│   │   └── [name].[hash].css.map
+│   │
+│   └── js
+│       ├── [name].[hash].js
+│       ├── [name].[hash].js.LICENSE.txt
+│       └── [name].[hash].js.map
+│
+└── html
+    └── [name]
+        └── index.html
+```
+
+最常见的产物是 HTML 文件、JS 文件和 CSS 文件：
+
+- HTML 文件：默认输出到 `html` 目录。
+- JS 文件：默认输出到 `static/js` 目录，
+- CSS 文件：默认输出到 `static/css` 目录。
+
+此外，JS 文件和 CSS 文件有时候会生成一些相关产物：
+
+- License 文件：包含开源许可证信息，默认输出到 JS 文件的同级目录，并添加 `.LICENSE.txt` 后缀。
+- Source Map 文件：包含保存源代码映射关系，默认输出到 JS 文件和 CSS 文件的同级目录，并添加 `.map` 后缀。
+
+在产物的文件名称中，`[name]` 表示这个文件对应的入口名称，比如 `index`, `main`。`[hash]` 则是基于该文件的内容生成的哈希值。
+
+## 修改产物目录
+
+Modern.js 提供了多个配置项来修改产物目录和产物名称，你可以：
+
+- 通过 [output.filename](/configure/app/output/filename) 来修改产物的文件名。
+- 通过 [output.distPath](/configure/app/output/dist-path) 来修改产物的输出路径。
+- 通过 [output.legalComments](/configure/app/output/legal-comments) 来修改 License 文件的生成方式。
+- 通过 [output.sourceMap](/configure/app/output/source-map) 来移除 Source Map 文件。
+- 通过 [html.outputStructure](/configure/app/html/output-structure) 移除 HTML 产物对应的文件夹。
+
+## 静态资源
+
+当你在代码中引用图片、SVG、字体、媒体等类型的静态资源时，它们也会被输出到 `dist/static` 目录下，并根据静态资源类型来自动分配到对应的子目录：
+
+```bash
+dist
+└── static
+    ├── image
+    │   └── foo.[hash].png
+    │
+    ├── svg
+    │   └── bar.[hash].svg
+    │
+    ├── font
+    │   └── baz.[hash].woff2
+    │
+    └── media
+        └── qux.[hash].mp4
+```
+
+你可以通过 [output.distPath](/configure/app/output/dist-path) 配置项将这些静态资源统一输入到单个目录下，比如输出到 `assets` 目录：
+
+```ts
+export default {
+  output: {
+    distPath: {
+      image: 'assets',
+      svg: 'assets',
+      font: 'assets',
+      media: 'assets',
+    },
+  },
+};
+```
+
+上方的配置会生成以下目录结构：
+
+```bash
+dist
+└── assets
+    ├── foo.[hash].png
+    ├── bar.[hash].svg
+    ├── baz.[hash].woff2
+    └── qux.[hash].mp4
+```
+
+## 扁平化产物目录
+
+有时候你不想产物目录有太多层级，可以将目录设置为空字符串，使生成的产物目录扁平化。
+
+参考下方的例子：
+
+```ts
+export default {
+  output: {
+    distPath: {
+      js: '',
+      css: '',
+      html: '',
+    },
+  },
+  html: {
+    outputStructure: 'flat',
+  },
+};
+```
+
+上方的配置会生成以下目录结构：
+
+```bash
+dist
+├── [name].[hash].css
+├── [name].[hash].css.map
+├── [name].[hash].js
+├── [name].[hash].js.map
+└── [name].html
+```
+
+## 产物不写入磁盘
+
+默认情况下，Modern.js 会将构建产物写入磁盘，以方便开发者查看产物的内容，或是配置静态资源的代理规则。
+
+在开发环境，你可以选择将构建产物保存在 Dev Server 的内存中，从而减少文件操作产生的开销。
+
+将 `dev.writeToDisk` 配置项设置为 `false` 即可：
+
+```ts
+export default {
+  dev: {
+    writeToDisk: false,
+  },
+};
+```

package/docs/zh/guides/basic-features/render/_meta.json

@@ -0,0 +1,10 @@
+[
+  "overview",
+  "ssr",
+  "streaming-ssr",
+  "ssr-cache",
+  "ssg",
+  "rsc",
+  "tanstack-rsc",
+  "before-render"
+]

package/docs/zh/guides/basic-features/render/before-render.mdx

@@ -0,0 +1,108 @@
+# 渲染预处理
+
+在某些场景下，应用需要在渲染前执行预处理操作。Modern.js 推荐使用 **[Runtime 插件 (Runtime Plugin)](/plugin/introduction.html#runtime-插件)** 来实现这类逻辑。
+
+## 定义 Runtime 插件
+
+```ts
+import type { RuntimePlugin } from '@modern-js/runtime';
+
+const myRuntimePlugin = (): RuntimePlugin => ({
+  name: 'my-runtime-plugin',
+  setup: api => {
+    api.onBeforeRender(context => {
+      // 在渲染前执行的逻辑
+      console.log('Before rendering:', context);
+    });
+  },
+});
+
+export default myRuntimePlugin;
+```
+
+## 注册插件
+
+在项目 `src/modern.runtime.ts` 文件中注册插件：
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import myRuntimePlugin from './plugins/myRuntimePlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myRuntimePlugin()],
+});
+```
+
+## 应用场景 -- 全局数据注入
+
+通过 `onBeforeRender` 钩子的 `context` 参数，可以向应用注入全局数据。应用的组件可以通过 `use(RuntimeContext)` Hook 访问这些数据。
+
+:::info
+
+此功能在以下场景中特别有用：
+
+- 需要页面级前置数据的应用
+- 自定义数据注入流程
+- 框架迁移场景（例如从 Next.js 迁移）
+
+:::
+
+**定义数据注入插件**
+
+```ts
+import type { RuntimePlugin } from '@modern-js/runtime';
+
+const dataInjectionPlugin = (): RuntimePlugin => ({
+  name: 'data-injection-plugin',
+  setup: api => {
+    api.onBeforeRender(context => {
+      // 向 context 中注入数据
+      context.message = 'Hello World';
+    });
+  },
+});
+
+export default dataInjectionPlugin;
+```
+
+**在组件中使用注入的数据**
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+export default function MyComponent() {
+  const context = use(RuntimeContext);
+  const { message } = context;
+
+  return <div>{message}</div>;
+}
+```
+
+**结合 SSR 使用**
+
+在 SSR 场景下，浏览器端可以获取服务端渲染期间通过 `onBeforeRender` 注入的数据。开发者可以根据需求决定是否在浏览器端重新获取数据来覆盖服务端数据。
+
+```ts
+import type { RuntimePlugin } from '@modern-js/runtime';
+
+const dataInjectionPlugin = (): RuntimePlugin => ({
+  name: 'data-injection-plugin',
+  setup: api => {
+    api.onBeforeRender(context => {
+      if (process.env.MODERN_TARGET === 'node') {
+        // 服务端渲染时设置数据
+        context.message = 'Hello World By Server';
+      } else {
+        // 客户端渲染时检查数据
+        if (!context.message) {
+          // 如果没有获取到服务端数据，则设置客户端数据
+          context.message = 'Hello World By Client';
+        }
+      }
+    });
+  },
+});
+
+export default dataInjectionPlugin;
+```