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

package/docs/zh/guides/basic-features/debug/mock.mdx

@@ -0,0 +1,102 @@
+---
+sidebar_position: 5
+---
+
+# 数据模拟（Mock）
+
+Modern.js 提供了快速生成 Mock 数据的功能，能够让前端独立自主开发，不被后端接口阻塞。
+
+## 启用 Mock
+
+约定当 `config/mock` 目录下存在 `index.ts` 时，会自动开启 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
+export default {
+  /* 属性为具体的 method 和 请求 url，值为 object 或 array 作为请求的结果 */
+  'GET /api/getInfo': { data: [1, 2, 3, 4] },
+
+  /* method 默认为 GET */
+  '/api/getExample': { id: 1 },
+
+  /* 可以使用自定义函数根据请求动态返回数据, req & res 都是 Node.js HTTP 原生对象 */
+  '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);
+  },
+};
+```
+
+## 按需使用 Mock 服务
+
+`config/mock/index.ts` 下还可以导出 `config` 对象，更精细的控制 Mock 服务。
+
+```ts
+import type { IncomingMessage } from 'node:http';
+import type { ServerResponse } from 'node:http';
+
+type MockConfig = {
+  enable: ((req: IncomingMessage, res: ServerResponse) => boolean) | boolean;
+};
+
+export const config = {
+  enable: false
+}
+```
+
+目前仅支持 `enable` 配置，开发者可以通过该配置控制是否执行 Mock。
+
+:::note
+修改 `config` 后无需重启服务，即刻生效。
+:::

package/docs/zh/guides/basic-features/debug/proxy.mdx

@@ -0,0 +1,25 @@
+---
+sidebar_position: 6
+---
+
+# 本地代理
+
+Modern.js 在 [`dev.server.proxy`](/configure/app/dev/server) 中提供了配置开发环境代理的方式。
+
+例如，将本地开发接口代理到其他地址：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  dev: {
+    server: {
+      proxy: {
+        // http://localhost:8080/api -> https://example.com/api
+        // http://localhost:8080/api/foo -> https://example.com/api/foo
+        '/api': 'https://example.com',
+      },
+    },
+  },
+});
+```

package/docs/zh/guides/basic-features/debug/rsdoctor.mdx

@@ -0,0 +1,48 @@
+# 使用 Rsdoctor
+
+Rsdoctor 是一个 Rspack 构建分析工具。在 Modern.js 中，我们推荐使用 Rsdoctor 来对构建过程与构建产物进行诊断和分析。
+
+Modern.js 默认会在生产构建中开启 Rsdoctor。
+
+## 执行构建
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  performance: {
+    // 在 production build 默认启用
+    rsdoctor: true,
+  },
+});
+```
+
+```bash
+npm run build
+```
+
+## 关闭 Rsdoctor
+
+如果你希望关闭 Rsdoctor：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  performance: {
+    rsdoctor: false,
+  },
+});
+```
+
+你也可以使用对象形式：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  performance: {
+    rsdoctor: {
+      enabled: true,
+    },
+  },
+});
+```
+
+## 相关文档
+
+更多内容请查阅 [Rsdoctor 官网文档](https://rsdoctor.rs/)。

package/docs/zh/guides/basic-features/debug/using-storybook.mdx

@@ -0,0 +1,92 @@
+---
+sidebar_position: 15
+---
+
+import { PackageManagerTabs } from '@theme'
+
+# 使用 Storybook
+
+[Storybook](https://storybook.js.org/) 是一个专门用于组件调试的工具，它围绕着组件开发提供了：
+
+- 丰富多样的调试能力
+- 可与一些测试工具结合使用
+- 可重复使用的文档内容
+- 可分享能力
+- 工作流程自动化
+
+## 原理
+
+Rsbuild 提供了 [Storybook Rsbuild](https://storybook.rsbuild.rs/index.html)，任何 Rsbuild 的项目都可以使用该工具来实现 Storybook 的构建。
+
+Modern.js 基于此工具实现了 `storybook-addon-modernjs`，该插件会加载 Modern.js 配置文件，并转换为 **Storybook Rsbuild** 可用的配置。
+
+:::info
+本文档仅提供最简单的使用方式，更多内容可参考 [Storybook Rsbuild Modern.js 集成](https://storybook.rsbuild.rs/guide/integrations/modernjs.html)。
+:::
+
+## 安装
+
+<PackageManagerTabs command="install @rsbuild/core storybook-builder-rsbuild storybook-addon-modernjs -D" />
+
+你需要在项目中安装 `@rsbuild/core`，否则该插件可能无法正常工作。
+
+## 配置 `.storybook/main.ts`
+
+```ts
+import type { StorybookConfig } from 'storybook-react-rsbuild'
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  addons: ['storybook-addon-modernjs'],
+  framework: 'storybook-react-rsbuild',
+}
+export default config
+```
+
+## Storybook 中进行 BFF 一体化调用
+
+当你希望在 Storybook 的组件中直接调用 BFF 接口（例如请求 `/api/**`）时，需要同时启动 BFF 服务并在 Storybook 的开发服务器中设置代理，避免跨域问题。
+
+### 1. 增加 scripts
+
+在 `package.json` 中增加以下脚本，用于单独启动 BFF 服务和 Storybook，同时通过 `BFF_PROXY` 环境变量确保代理配置仅在 Storybook 构建时生效：
+
+```json
+{
+  "scripts": {
+    "dev:api": "modern dev --api-only",
+    "storybook": "BFF_PROXY=1 storybook dev -p 6006 --no-open",
+  }
+}
+```
+
+### 2. 配置代理解决跨域
+
+在 `modern.config.ts` 中增加以下配置，仅在 Storybook 构建时将请求代理到 BFF 服务：
+
+```ts
+export default applyBaseConfig({
+  dev: process.env.BFF_PROXY
+    ? {
+        server: {
+          proxy: {
+            `${bff.prefix || '/api'}`: `http://localhost:${server.port || '8080'}`,
+          },
+        },
+      }
+    : {},
+});
+```
+
+### 3. 启动方式
+
+```bash
+pnpm dev:api
+pnpm storybook
+```
+
+此时在组件中直接请求 `bff.prefix` 对应的路径即可完成 BFF 一体化调用；如果未配置，则请求 `/api/**`。
+
+## 示例
+
+你可以查看 [示例](https://github.com/rspack-contrib/storybook-rsbuild/tree/main/sandboxes/modernjs-react) 了解 Modern.js 中使用 Storybook 的方式。

package/docs/zh/guides/basic-features/deploy.mdx

@@ -0,0 +1,432 @@
+---
+sidebar_position: 15
+---
+
+# 部署应用
+
+目前，Modern.js 提供了两种部署方式：
+
+- 你可以将应用自行托管在包含 Node.js 环境的容器中，这为应用提供了部署的灵活性。
+- 你也可以通过平台部署应用，目前 Modern.js 官方支持了 [Netlify](https://www.netlify.com/), [Vercel](https://vercel.com/) 和 [Github pages](https://pages.github.com/) 平台。
+
+:::info
+目前 Modern.js 仅支持在 Node.js 环境中运行，未来将提供更多运行时环境的支持。
+:::
+
+## 构建部署产物
+
+执行 `modern deploy` 命令将自动输出部署产物。此过程包括优化 Bundler 构建产物及产物依赖，检测当前部署平台，并自动生成可以在该平台运行的产物。
+如果你希望在本地生成并测试特定部署平台的产物，可以通过设置环境变量来指定平台：
+
+```bash
+MODERNJS_DEPLOY=netlify npx modern deploy
+```
+
+:::info
+在 Modern.js 官方支持的部署平台中部署时，无需指定环境变量。
+:::
+
+## ModernJS 内置 Node.js 服务器
+
+### 单仓库项目
+
+默认情况下，如果未检测到 Modern.js 支持的部署平台，Modern.js 将生成可以在 Node.js 环境下运行的部署产物。
+
+你可以使用以下命令构建项目：
+
+```bash
+npx modern deploy
+```
+
+当执行 `modern deploy` 命令时，Modern.js 将生成可执行的部署产物，并在控制台输出以下内容：
+
+```bash
+Static directory: `.output/static`
+You can preview this build by `node .output/index`
+```
+
+现在，你可以通过执行 `node .output/index` 命令来运行服务器。在 `.output/static` 目录中，存放了页面运行所需的静态资源，你可以选择将这些资源上传到 CDN 以提高访问速度。
+
+:::info
+默认情况下，运行 Modern.js 服务器时会监听 8080 端口，如果你想修改监听的端口，可以指定 `PORT` 环境变量：
+
+```
+PORT=3000 node .output/index
+```
+
+:::
+
+### Monorepo
+
+对于 Monorepo 项目，除了需要构建当前的项目外，还需要构建当前项目依赖的仓库中其他子项目。
+
+假设当前项目的 `package.json` 中的 name 为 `app`，以 pnpm 作为 Monorepo 管理工具为例，你可以在项目 `package.json` 中添加以下命令用于构建：
+
+```json title="app/package.json"
+{
+  "scripts": {
+    "build:packages": "pnpm --filter 'app^...' run build",
+    "deploy": "pnpm run build:packages && modern deploy"
+  }
+}
+```
+
+如果你使用 rush 作为 Monorepo 管理工具，可以在 `package.json` 中添加以下命令：
+
+```json
+{
+  "scripts": {
+    "build:packages": "rush rebuild --to-except app",
+    "deploy": "rushx build:packages && modern deploy"
+  }
+}
+```
+
+构建完成后，框架会将项目中所有的依赖生成在 `.output/node_modules` 目录下。你同样可以使用 `node .output/index` 运行 Modern.js 服务器。
+
+## Netlify
+
+Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现代 Web 项目而设计。在 Netlify 上部署，通常需要配置 `netlify.toml` 文件，你可以根据项目复杂度，渐进地配置该文件。
+
+### 纯前端项目
+
+在当前项目的根目录添加 `netlify.toml` 文件：
+
+```bash
+./
+├── src
+├── modern.config.ts
+├── netlify.toml
+└── package.json
+```
+
+在 `netlify.toml` 中添加以下内容：
+
+```toml
+[build]
+  publish = "dist"
+  command = "modern deploy"
+```
+
+:::info
+你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
+:::
+
+在 Netlify 平台上添加项目，部署即可。
+
+### 全栈项目
+
+全栈项目是指使用了自定义 Web Server、SSR、BFF 的项目，这些项目需要部署在 **Netlify Functions** 上。你需要基于上述的 `netlify.toml` 文件，添加以下配置：
+
+```toml title="netlify.toml"
+[build]
+  publish = "dist"
+  command = "modern deploy"
+
+[functions]
+  directory = ".netlify/functions"
+  node_bundler = "none"
+  included_files = [".netlify/functions/**"]
+
+```
+
+:::info
+
+1. 目前 Modern.js 还不支持在 Netlify Edge Functions 进行部署，我们将在后续的版本中支持。
+2. 你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr)。
+
+:::
+
+### Monorepo 项目
+
+:::info
+以下指南主要针对于全栈项目，对于纯 CSR 的项目，只需要按照[纯前端项目](#纯前端项目)部署即可。
+:::
+
+对于 Monorepo 项目，除了需要构建当前的项目外，还需要构建当前项目依赖的仓库中其他子项目。这里以一个 pnpm Monorepo 仓库为例，在 Netlify 上对 Monorepo 项目进行部署。
+
+假设 Monorepo 仓库目录结构如下：
+
+```
+.
+├── packages
+│   ├── app
+│   └── app-dep1
+├── package.json
+├── pnpm-lock.yaml
+└── pnpm-workspace.yaml
+```
+
+你需要在 Netlify 平台上配置 **Base directory** 为 `packages/app`:
+
+<img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/netlify-monorepo-basedir.png?x-resource-account=public" />
+
+在 `packages/app/package.json` 中添加以下 script，在执行 `app` 仓库的部署命令之前，先执行 workspace 中其他仓库的构建：
+
+```json
+{
+  "scripts": {
+    "build:packages": "pnpm --filter 'app^...' run build",
+    "deploy": "pnpm run build:packages && modern deploy"
+  }
+}
+```
+
+在 `netlify.toml` 配置构建命令：
+
+```toml
+[build]
+  publish = "dist"
+  command = "npm run deploy"
+
+[functions]
+  directory = ".netlify/functions"
+  node_bundler = "none"
+  included_files = [".netlify/functions/**"]
+```
+
+提交你的代码，使用 Netlify 平台部署即可。
+
+## Vercel
+
+Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的功能，支持部署静态网站，服务端渲染应用等。在 Vercel 上部署，通常需要配置 `vercel.json` 文件，你可以根据项目复杂度，渐进地配置该文件。
+
+### 纯前端项目
+
+在当前项目的根目录添加 `vercel.json` 文件：
+
+```bash
+./
+├── src
+├── modern.config.ts
+├── vercel.json
+└── package.json
+```
+
+在 `vercel.json` 中添加以下内容：
+
+```json title="vercel.json"
+{
+  "buildCommand": "modern deploy",
+  "outputDirectory": ".vercel/output"
+}
+```
+
+提交你的项目到 git，在 Vercel 平台上选择 Frmeworkwork Preset 为 `Other`，部署即可。
+
+<img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/vercel-framework-preset.png" />
+
+:::info
+你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
+:::
+
+### 全栈项目
+
+全栈项目是指使用了自定义 Web Server、SSR、BFF 的项目，这些项目需要部署在 **Vercel Functions** 上。
+
+全栈项目除了按照[纯前端项目](#纯前端项目)的方式配置 `vercel.json` 外，有两点需要注意：
+
+1. 当前，Modern.js 还不支持在 Vercel 平台上部署 BFF 项目，我们将在后续的版本中支持。
+2. 函数运行的 node.js 版本由项目在 Vercel 平台配置决定。
+
+:::info
+你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr)。
+
+:::
+
+### Monorepo 项目
+
+:::info
+以下指南主要针对于全栈项目，对于纯 CSR 的项目，只需要按照[纯前端项目](#纯前端项目-1)部署即可。
+:::
+
+对于 Monorepo 项目，除了需要构建当前的项目外，还需要构建当前项目依赖的仓库中其他子项目。这里以一个 pnpm Monorepo 仓库为例，在 Vercel 上对 Monorepo 项目进行部署。
+
+假设 Monorepo 仓库目录结构如下：
+
+```
+.
+├── packages
+│   ├── app
+│   └── app-dep1
+├── package.json
+├── pnpm-lock.yaml
+└── pnpm-workspace.yaml
+```
+
+首先，你需要在 Vercel 平台上配置 **Root Directory** 为 `packages/app`:
+
+<img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/vercel-root-directory.png" />
+
+将 Node.js 运行时设置为 `20.x`：
+
+```json title="package.json"
+"engines": {
+  "node": "20.x"
+},
+```
+
+在 `packages/app/package.json` 中添加以下 script，在执行 `app` 仓库的部署命令之前，先执行 workspace 中其他仓库的构建：
+
+```json
+{
+  "scripts": {
+    "build:packages": "pnpm --filter 'app^...' run build",
+    "deploy": "pnpm run build:packages && modern deploy"
+  }
+}
+```
+
+在 `packages/app/vercel.json` 文件中添加以下内容：
+
+```json title="vercel.json"
+{
+  "buildCommand": "npm run deploy",
+  "outputDirectory": ".vercel/output"
+}
+```
+
+提交你的代码，使用 Vercel 平台部署即可。
+
+## Github Pages
+
+如果你要为一个仓库创建 Github 页面，并且你没有自定义域名，则该页面的 URL 将会是以下格式：`http://<username>.github.io/<repository-name>`，所以需要在 `modern.config.ts` 中添加
+以下配置：
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  //...
+  server: {
+    baseUrl: '/<repository-name>',
+  },
+  output: {
+    assetPrefix: '/<repository-name>',
+  },
+});
+```
+
+Github Pages 支持两种部署方式，通过分支部署或通过 Github Actions 部署，如果通过分支部署，可以使用以下步骤：
+
+1. 在 github 仓库中，选择 `Settings > Pages > Source > Deploy from a branch`。
+2. 安装 `gh-pages` 依赖作为开发依赖。
+3. 在 package.json 的 `scripts` 中添加 `"deploy:gh-pages": "MODERNJS_DEPLOY=ghPages modern deploy && gh-pages -d .output"`。
+4. 执行 `npm run deploy:gh-pages`。
+
+:::info
+
+1. 执行 `MODERNJS_DEPLOY=ghPages modern deploy`，Modern.js 会把可用于 github 部署的产物构建到 `.output` 目录。
+2. 可以参考项目[示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
+
+:::
+
+如果通过 Github Actions 部署，可以选择 Settings > Pages > Source > GitHub Actions，并在项目中添加 workflow 文件，可参考[示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
+
+## 自建 Node.js 服务器
+
+通常情况下，我们推荐使用 Modern.js 内置的 Node.js 服务器来部署应用，它支持托管纯前端项目或者全栈项目，并且保证在开发和生产环境下的表现一致。
+
+如果你的项目是纯前端项目，也可以通过自建 Node.js 服务器来部署应用，以下用一个 Koa 服务器的示例来演示如何托管一个纯前端项目的产物。
+
+例如你有一个 Node.js 服务器的仓库，你可以将项目的产物复制到该仓库下，现在结构如下：
+
+```bash
+.
+├── .output
+│   ├── html
+│   └── static
+└── server.js
+```
+
+在 `server.js` 中，假定有如下代码：
+
+```ts title="server.js"
+import Koa from 'koa';
+
+const app = new Koa();
+app.use(async (ctx, next) => {
+  ctx.body = 'Hello Modern.js';
+});
+app.listen(3000);
+```
+
+现在，你可以新增部分代码，将静态资源和 HTML 文件的访问逻辑添加到 `server.js` 中。这里需要通过 `mime-types` 包来获取静态资源的 MIME 类型，因此我们先安装依赖：
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command="add mime-types" />
+
+```ts title="server.js"
+const Koa = require('koa');
+const fs = require('fs');
+const path = require('path');
+const mime = require('mime-types');
+
+const app = new Koa();
+app.use(async (ctx, next) => {
+  if (ctx.path.startsWith('/static')) {
+    ctx.type = mime.lookup(ctx.path);
+    ctx.body = fs.createReadStream(
+      path.resolve(__dirname, `.output${ctx.path}`),
+    );
+  } else if (ctx.path === '/') {
+    ctx.type = 'html';
+    ctx.body = fs.createReadStream(
+      path.resolve(__dirname, '.output/html/main/index.html'),
+    );
+  }
+});
+app.listen(3000);
+```
+
+:::note
+以上代码是最基础的例子，你的应用可能是多入口的，需要根据不同的路径访问不同的 HTML 文件，自建 Node.js 服务器也会存在更多的逻辑。
+:::
+
+需要注意的是，如果你的项目中使用 Modern.js 约定式路由，或是使用 React Router 自行搭建了浏览器端路由，你必须通过正确的 `baseURL` 来访问 HTML 文件。
+
+在 Modern.js 中，默认的 `baseURL` 是 `'/'`，你可以通过在 `modern.config.ts` 中修改 [`server.baseUrl`](/configure/app/server/base-url) 来配置。
+
+:::danger
+存在浏览器路由的项目，永远无法通过 `/index.html` 路径来访问到 HTML 文件。
+:::
+
+## Nginx
+
+Nginx 是一个高性能的 HTTP 和反向代理服务器，它可以处理静态文件、反向代理、负载均衡等功能。在 Nginx 上部署，通常需要配置 `nginx.conf` 文件。
+
+如果你的项目是纯前端项目，也可以通过 Nginx 来部署应用，以下提供一个 Nginx 配置的示例来演示如何托管一个纯前端项目的产物。
+
+```nginx title="nginx.conf"
+# user [user] [group];
+worker_processes 1;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    include       mime.types;
+    default_type  application/octet-stream;
+
+    server {
+        listen 8080;
+        server_name localhost;
+
+        location / {
+            # root [projectPath]/.output/html/main;
+            index index.html;
+            try_files $uri $uri/ =404;
+        }
+
+        location /static {
+          # alias [projectPath]/.output/static;
+        }
+    }
+}
+```
+
+在上述配置中，你需要将 `[projectPath]` 替换为你的项目路径，将 `[user]` 和 `[group]` 替换为你当前的用户和用户组。
+
+你可以将上述配置复制到 Nginx 安装目录的 `nginx.conf` 文件中，然后启动 Nginx 服务。你也可以通过 `nginx -c` 启动指定路径下的配置文件，此时你需要额外保证 `include` 指令配置的路径正确。