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

package/docs/zh/community/contributing-guide.mdx

@@ -0,0 +1,256 @@
+---
+sidebar_position: 3
+---
+
+# 贡献指南
+
+感谢你有兴趣为 Modern.js 做贡献！在开始你的贡献之前，请花几分钟时间阅读以下指南。
+
+## 设置开发环境
+
+### Fork 仓库
+
+[Fork](https://help.github.com/articles/fork-a-repo/) Modern.js 仓库到你的 GitHub 账户，然后 [clone](https://help.github.com/articles/cloning-a-repository/) 到你的本地。
+
+### 安装 Node.js
+
+我们推荐使用 Node.js 22。你可以通过以下命令查看当前使用的 Node.js 版本：
+
+```bash
+node -v
+```
+
+如果你当前环境没有安装 Node.js，可以使用 [nvm](https://github.com/nvm-sh/nvm)或者 [fnm](https://github.com/Schniz/fnm) 来安装它。
+
+以下是如何通过 nvm 安装 Node.js 22 LTS 版本的示例：
+
+```bash
+# 安装 Node.js 22 的 LTS 版本
+nvm install 22 --lts
+
+# 将新安装的 Node.js 22 设为默认版本
+nvm alias default 22
+
+# 切换到新安装的 Node.js 22
+nvm use 22
+```
+
+### 安装 pnpm
+
+```bash
+# 使用 corepack 启用 pnpm，仅在 Node.js >= `v14.19.0` 上可用
+corepack enable
+```
+
+### 安装依赖
+
+```sh
+pnpm install
+```
+
+这将完成：
+
+- 安装所有依赖项
+- 在 monorepo 中的 packages 之间创建 symlinks
+- 运行 `prepare` 脚本来构建所有包（这将需要一些时间，但可以保证所有包都被正确构建）
+
+> 在此之后，你通常不需要一次性构建所有 packages。如果你正在开发的新功能依赖另一个 package 的最新代码，通常只构建指定的 package 就足够了。
+
+### 设置 Git 邮箱
+
+请确保在 `<https://github.com/settings/emails>` 中设置了电子邮件，当你提交 Pull Request 时将需要它。
+
+检查你的 git 客户端是否已配置邮箱：
+
+```sh
+git config --list | grep email
+```
+
+全局设置邮箱：
+
+```sh
+git config --global user.email "SOME_EMAIL@example.com"
+```
+
+针对本地仓库设置邮箱：
+
+```sh
+git config user.email "SOME_EMAIL@example.com"
+```
+
+## 代码变更和构建
+
+当你在 fork 的仓库中设置完本地开发环境后，我们就可以开始开发了。
+
+### 创建一个新分支
+
+建议在一个新的分支上开发，这样便于后续提交 pull request：
+
+```sh
+git checkout -b MY_BRANCH_NAME
+```
+
+### 构建 Package
+
+要构建你要更改的 package，首先打开 package 目录，然后执行 `build` 命令：
+
+```sh
+# 将 some-path 替换为你要构建的 package 的路径
+cd ./packages/some-package
+pnpm run build
+```
+
+此外，你可以使用 `--filter` 选项从仓库根目录来构建指定的 package：
+
+```sh
+pnpm run --filter @modern-js/some-package build
+```
+
+构建所有包：
+
+```sh
+pnpm run prepare
+```
+
+如果你需要清理项目中的所有 `node_modules/*`，执行 `reset` 命令：
+
+```sh
+pnpm run reset
+```
+
+## 测试
+
+### 添加新测试
+
+如果你进行了 bugfix，或者添加了需要测试的代码，请添加一些测试代码。
+
+你可以在 `<PACKAGE_DIR>/tests` 文件夹中添加单元测试用例。测试语法基于 [Rstest](https://rstest.rs/)。
+
+### 运行单元测试
+
+在提交 pull request 之前，为了确保本次变更没有引入缺陷，你可以通过执行以下命令运行单元测试：
+
+```sh
+pnpm run test
+```
+
+你也可以使用 `--filter` 选项运行单个包的单元测试：
+
+```sh
+pnpm run --filter @modern-js/some-package test
+```
+
+### 运行 E2E 测试
+
+除了单元测试之外，Modern.js 仓库还包括端到端 (E2E) 测试，用于检查整个应用程序的功能。
+
+你可以执行 `test:e2e` 命令来运行 E2E 测试：
+
+```sh
+pnpm run test:e2e
+```
+
+如果需要运行指定的测试，可以添加关键字进行过滤：
+
+```sh
+# 只运行带有 copy-assets 关键词的测试用例
+npx rstest copy-assets
+```
+
+## Linting
+
+为了帮助保持代码风格的一致性和可读性，我们使用 ESLint 对代码进行校验。
+
+你可以执行以下命令来运行 Linter：
+
+```sh
+pnpm run lint
+```
+
+## Benchmarking
+
+你可以在 PR 的评论区中输入 `!bench-framework` 或 `!bench-module` 分别对 `@modern-js/app-tools` 和 `@modern-js/module-tools` 做性能测试（这需要你具有 Collaborator 及以上的权限）。
+
+你可以根据评论输出的对比表格，重点关注构建时间和产物体积相关的指标，辅助进行相关性能判断与决策。
+
+依赖安装相关指标由于需要前置的发包流程，因此数据相对有滞后性，仅供参考。
+
+## 文档
+
+目前 Modern.js 提供英文和中文文档。如果你熟悉中文，请同时更新中英文文档。否则，只需更新英文文档即可。
+
+你可以在 `packages/document` 文件夹中找到所有文档：
+
+```sh
+root
+└─ packages
+   └─ document # Modern.js Framework 文档
+```
+
+文档站使用 Rspress 构建，文档内容可以使用 markdown 或 mdx 语法编写。详细使用方法可以参考 [Rspress 文档](https://rspress.rs/)。
+
+Rspress 的源代码可以在 [这个仓库](https://github.com/web-infra-dev/rspress) 中找到。
+
+## 提交变更
+
+### 添加 Changeset
+
+Modern.js 使用 [Changesets](https://github.com/changesets/changesets) 来管理版本和 Changelog。
+
+如果你修改了一些包，则需要为本次变更添加一个新的变更集。请运行 `change` 命令来选择更改的包并添加 changeset 信息。
+
+```sh
+pnpm run change
+```
+
+### 提交你的变更
+
+提交变更到 fork 后的仓库，并 [创建 pull request](https://help.github.com/articles/creating-a-pull-request/)。
+
+### PR 标题格式
+
+PR 标题的格式遵循 Conventional Commits。
+
+一个例子：
+
+```
+feat(plugin-swc): 添加 `xxx` 配置项
+^ ^ ^
+| | |__ 主题
+| |_______ 范围
+|____________ 类型
+```
+
+## 发布
+
+Modern.js 使用 [Changesets](https://github.com/changesets/changesets) 来管理版本和 changelog。
+
+仓库的维护者可以将所有包的新版本发布到 npm。
+
+以下是发布的步骤（我们通常使用 CI 进行发布，并避免在本地发布 npm 包）：
+
+1. 拉取 `main` 分支的最新代码。
+2. 安装依赖：
+
+```sh
+pnpm i
+```
+
+3. 构建 packages：
+
+```sh
+pnpm prepare
+```
+
+4. 升级版本：
+
+```sh
+pnpm run bump
+```
+
+5. 提交版本变更。
+
+```sh
+git add .
+git commit -m "Release va.b.c"
+```

package/docs/zh/community/releases.mdx

@@ -0,0 +1,31 @@
+---
+sidebar_position: 2
+---
+
+# 版本发布
+
+## 更新日志
+
+请访问 [GitHub - Release](https://github.com/web-infra-dev/modern.js/releases) 来了解 Modern.js 每个版本的变更内容。
+
+## 版本规范
+
+Modern.js 遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/) 语义化版本规范。
+
+- 主版本号：包含不兼容的 API 变更。
+- 次版本号：包含向下兼容的功能性变更。
+- 修订号：包含向下兼容的问题修正。
+
+## 发版周期
+
+- Modern.js 通常在每周四发布一个正式版本。
+- 当出现较为严重的问题时，我们会在当天发布修订版本。
+- 我们期望保持 Modern.js v2 的稳定和兼容，目前没有发布下一个 Major 版本的计划。
+
+## 版本升级
+
+当你需要升级项目中的 Modern.js 版本时，可以使用 `modern upgrade` 命令，参考 [版本升级](/guides/get-started/upgrade)。
+
+```bash
+npx modern upgrade
+```

package/docs/zh/community/showcase.mdx

@@ -0,0 +1,15 @@
+---
+sidebar_position: 0
+---
+
+# 案例展示
+
+欢迎来到 Modern.js 的案例展示页面！在这里，我们展示了一些基于 Modern.js 所实现的网站。
+
+如果你使用 Modern.js 构建了一个网站，欢迎你与社区分享它。只需回复 [GitHub 讨论贴](https://github.com/web-infra-dev/modern.js/discussions/3554) 并附上你网站的链接即可。我们会定期收集内容，并将它们展示在当前页面。
+
+## 案例
+
+import { ShowcaseList } from '@site/src/components/ShowcaseList';
+
+<ShowcaseList />

package/docs/zh/community/team.mdx

@@ -0,0 +1,29 @@
+---
+sidebar_position: 1
+---
+
+# 开发团队
+
+Modern.js 的开发由字节跳动的 Modern.js 团队和社区贡献者驱动。
+
+## 核心团队成员
+
+以下是 Modern.js 团队的核心成员：
+
+import { RandomMemberList } from '@site/src/components/RandomMemberList';
+
+<RandomMemberList />
+
+## 所有贡献者
+
+感谢以下伙伴们为 Modern.js 做出的贡献：
+
+<a
+  href="https://github.com/web-infra-dev/modern.js/graphs/contributors"
+  style={{ display: 'block', marginTop: 24 }}
+>
+  <img
+    src="https://opencollective.com/modernjs/contributors.svg?width=890&button=false"
+    alt="contributors"
+  />
+</a>

package/docs/zh/components/bff-operator-code.mdx

@@ -0,0 +1,5 @@
+import FrameworkCode from '@site/src/components/FrameworkCode';
+
+<FrameworkCode sourcePath="@modern-js/plugin-bff/hono-server">
+  {props.children}
+</FrameworkCode>

package/docs/zh/components/bff-upload.mdx

@@ -0,0 +1,98 @@
+### BFF 函数
+
+首先创建 `api/lambda/upload.ts` 文件：
+
+```ts title="api/lambda/upload.ts"
+export const post = async ({ formData }: { formData: Record<string, any> }) => {
+  console.info('formData:', formData);
+  // do somethings
+  return {
+    data: {
+      code: 0,
+    },
+  };
+};
+```
+
+:::tip
+通过接口处理函数入参中的 `formData` 可以获取客户端上传的文件。值为 `Object`，key 为上传时的字段名。
+:::
+
+### 一体化调用
+
+接着在 `src/routes/upload/page.tsx` 中直接引入函数并调用：
+
+```tsx title="routes/upload/page.tsx"
+import { post } from '@api/upload';
+import React, { type JSX } from 'react';
+
+export default (): JSX.Element => {
+  const [file, setFile] = React.useState<FileList | null>();
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    setFile(e.target.files);
+  };
+
+  const handleSubmit = async (e: React.MouseEvent<HTMLButtonElement>) => {
+    e.preventDefault();
+    const formData = new FormData();
+    if (file) {
+      for (let i = 0; i < file.length; i++) {
+        formData.append('images', file[i]);
+      }
+      post({
+        formData,
+      });
+    }
+  };
+
+  return (
+    <div>
+      <input multiple type="file" onChange={handleChange} />
+      <button onClick={handleSubmit}>upload</button>
+    </div>
+  );
+};
+```
+
+:::tip
+注意：入参类型必须为：`{ formData: FormData }` 才会正确上传。
+
+:::
+
+### 手动上传
+
+可以基于 `fetch API` 手动上传文件，需要在调用 `fetch` 时，将 `body` 设置为 `FormData` 类型并提交 `post` 请求。
+
+```tsx title="routes/upload/page.tsx"
+import React from 'react';
+
+export default (): JSX.Element => {
+  const [file, setFile] = React.useState<FileList | null>();
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    setFile(e.target.files);
+  };
+
+  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData();
+    if (file) {
+      for (let i = 0; i < file.length; i++) {
+        formData.append('images', file[i]);
+      }
+      await fetch('/api/upload', {
+        method: 'POST',
+        body: formData,
+      });
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input multiple type="file" onChange={handleChange} />
+      <button type="submit">upload</button>
+    </form>
+  );
+};
+```

package/docs/zh/components/build-output.mdx

@@ -0,0 +1,45 @@
+在项目中执行 `pnpm run build` 即可构建项目生产环境产物：
+
+```bash
+$ pnpm run build
+
+> modern build
+
+  Modern.js Framework
+
+info    Starting production build...
+info    Type checker is enabled. It may take some time.
+ready   Client compiled in 6.19 s
+info    Production file sizes:
+
+  File                                       Size        Gzipped
+  dist/routes-manifest.json                  0.74 kB     0.28 kB
+  dist/static/css/async/page.d7915515.css    1.4 kB      0.69 kB
+  dist/static/js/main.5ae469e7.js            3.0 kB      1.3 kB
+  dist/html/index/index.html                  6.0 kB      2.6 kB
+  dist/static/js/async/page.ddc8a4c1.js      19.2 kB     6.7 kB
+  dist/static/js/34.171fffdb.js              21.3 kB     7.1 kB
+  dist/static/js/lib-router.8995a55e.js      55.3 kB     18.1 kB
+  dist/static/js/lib-lodash.53ec3384.js      71.4 kB     24.8 kB
+  dist/static/js/lib-react.b5856db9.js       140.0 kB    45.2 kB
+  dist/static/js/lib-polyfill.86c452b3.js    213.3 kB    69.9 kB
+
+  Total size:  531.8 kB
+  Gzipped size:  176.7 kB
+```
+
+构建产物默认生成到 `dist/`，目录结构如下：
+
+```
+dist
+├── html
+│   └── index
+├── modern.config.json
+├── route.json
+├── routes-manifest.json
+└── static
+    ├── css
+    └── js
+```
+
+> 如果你需要自定义构建产物的目录，请参考 [构建产物目录](/guides/basic-features/output-files)。

package/docs/zh/components/bundler.mdx

@@ -0,0 +1,3 @@
+指 [Rspack](https://rspack.rs/) 等模块打包工具。
+
+打包工具的主要目标是将 JavaScript、CSS 等文件打包在一起，打包后的文件可以在浏览器、Node.js 等环境中使用。当 Bundler 处理 Web 应用时，它会构建一个依赖关系图，其中包含应用需要的各个模块，然后将所有模块打包成一个或多个 bundle。

package/docs/zh/components/debug-app.mdx

@@ -0,0 +1,16 @@
+在项目中执行 `pnpm run dev` 即可启动项目：
+
+```bash
+$ pnpm run dev
+
+> modern dev
+
+  Modern.js Framework
+
+ready   Client compiled in 0.86 s
+
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+在浏览器中打开 `http://localhost:8080/`，可以看到页面内容。

package/docs/zh/components/default-browserslist.mdx

@@ -0,0 +1,7 @@
+
+```yaml title=".browserslistrc"
+chrome >= 87
+edge >= 88
+firefox >= 78
+safari >= 14
+```

package/docs/zh/components/deploy-command.mdx

@@ -0,0 +1,14 @@
+## modern deploy
+
+`modern deploy` 命令，用于生成部署平台需要的产物。
+
+```bash
+Usage: modern deploy [options]
+
+Options:
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -s --skip-build       跳过构建阶段
+  -h, --help            显示命令帮助
+```
+
+详细内容可以参考 [部署应用](/guides/basic-features/deploy)。

package/docs/zh/components/deploy.mdx

@@ -0,0 +1 @@
+本地验证完成后，可以参考 [部署](/guides/basic-features/deploy.html) 一节，将项目部署到服务器上。

package/docs/zh/components/enable-bff-caution.mdx

@@ -0,0 +1,4 @@
+:::tip
+请先参考 [基础用法](/guides/advanced-features/bff/function.html#启用-bff) 中的"启用 BFF"部分，完成 BFF 功能的启用。
+
+:::

package/docs/zh/components/enable-bff.mdx

@@ -0,0 +1,56 @@
+要在 Modern.js 项目中启用 BFF 功能，请按照以下步骤修改代码：
+
+1. 安装 BFF 插件依赖
+
+如果项目尚未安装 BFF 插件，请先安装：
+
+```bash
+pnpm add @modern-js/plugin-bff
+```
+
+:::tip 版本一致性
+请确保 `@modern-js/plugin-bff` 的版本与项目中 `@modern-js/app-tools` 的版本保持一致。Modern.js 的所有官方包使用统一版本号发布，版本不一致可能导致兼容性问题。
+
+请先查看 `@modern-js/app-tools` 的版本，然后安装相同版本的 `@modern-js/plugin-bff`：
+
+```bash
+# 查看当前 @modern-js/app-tools 的版本
+pnpm list @modern-js/app-tools
+
+# 安装相同版本的 @modern-js/plugin-bff
+pnpm add @modern-js/plugin-bff@<版本号>
+```
+
+:::
+
+2. 配置 `modern.config.ts`
+
+在 `modern.config.ts` 文件中导入并添加 BFF 插件：
+
+```ts title="modern.config.ts"
+import { defineConfig, appTools } from '@modern-js/app-tools';
+import { bffPlugin } from '@modern-js/plugin-bff';
+
+export default defineConfig({
+  plugins: [appTools(), bffPlugin()],
+});
+```
+
+3. 配置 TypeScript 别名
+
+为了在 TypeScript 中正确识别 `@api` 别名，建议在 `tsconfig.json` 中添加路径映射：
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "paths": {
+      ..., // other paths,
+      "@api/*": ["./api/lambda/*"]
+    }
+  },
+  "include": [
+    ..., // 其他 include 目录
+    "api"  // 添加 api 目录
+  ]
+}
+```

package/docs/zh/components/enable-ssg.mdx

@@ -0,0 +1,49 @@
+要在 Modern.js 项目中启用 SSG 功能，请按照以下步骤修改代码：
+
+1. 安装 SSG 插件依赖
+
+如果项目尚未安装 SSG 插件，请先安装：
+
+```bash
+pnpm add @modern-js/plugin-ssg
+```
+
+:::tip 版本一致性
+
+请确保 `@modern-js/plugin-ssg` 的版本与项目中 `@modern-js/app-tools` 的版本保持一致。Modern.js 的所有官方包使用统一版本号发布，版本不一致可能导致兼容性问题。
+
+请先查看 `@modern-js/app-tools` 的版本，然后安装相同版本的 `@modern-js/plugin-ssg`：
+
+```bash
+# 查看当前 @modern-js/app-tools 的版本
+pnpm list @modern-js/app-tools
+
+# 安装相同版本的 @modern-js/plugin-ssg
+pnpm add @modern-js/plugin-ssg@<版本号>
+```
+
+:::
+
+2. 配置 modern.config.ts
+
+在 `modern.config.ts` 文件中导入并添加 SSG 插件，同时配置 `output.ssg`：
+
+```ts title="modern.config.ts"
+import { defineConfig, appTools } from '@modern-js/app-tools';
+import { ssgPlugin } from '@modern-js/plugin-ssg';
+
+export default defineConfig({
+  plugins: [appTools(), ssgPlugin()],
+  output: {
+    ssg: true,
+  },
+});
+```
+
+:::info 适用范围
+
+- 单入口请使用 `output.ssg`。
+- 多入口请使用 `output.ssgByEntries`。
+- 当仅设置 `output.ssg: true` 且未配置 `output.ssgByEntries` 时，所有入口下的所有路由都会作为 SSG 路由处理。
+
+:::

package/docs/zh/components/entry-scan-logic.mdx

@@ -0,0 +1,7 @@
+:::tip 入口扫描逻辑
+- 如果 `src/` 本身满足入口条件 → 单入口应用
+- 如果 `src/` 不满足条件 → 扫描 `src/` 下的子目录 → 多入口应用
+- 单入口应用中，默认入口名为 `index`
+
+:::
+

package/docs/zh/components/extend-bff-function.mdx

@@ -0,0 +1,3 @@
+普通的 BFF 函数写法有时并不能满足需求，例如业务场景下复杂的 TS 类型需要，Modern.js 提供了一种更强大的 BFF 函数写法。
+
+详细内容可参考 - [创建可扩展的 BFF 函数](/guides/advanced-features/bff/operators)。