@modern-js/main-doc 2.14.0 → 2.16.0

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

@@ -0,0 +1,267 @@
+---
+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 16 或 18。你可以通过以下命令查看当前使用的 Node.js 版本：
+
+```bash
+node -v
+#v16.18.0
+```
+
+如果你当前环境没有安装 Node.js，可以使用 [nvm](https://github.com/nvm-sh/nvm)或者 [fnm](https://github.com/Schniz/fnm) 来安装它。
+
+以下是如何通过 nvm 安装 Node.js 16 LTS 版本的示例：
+
+```bash
+# 安装 Node.js 16 的 LTS 版本
+nvm install 16 --lts
+
+# 将新安装的 Node.js 16 设为默认版本
+nvm alias default 16
+
+# 切换到新安装的 Node.js 16
+nvm use 16
+```
+
+### 安装 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 运行重置
+```
+
+---
+
+## 测试
+
+### 添加新测试
+
+如果你进行了 bugfix，或者添加了需要测试的代码，请添加一些测试代码。
+
+你可以在 `<PACKAGE_DIR>/tests` 文件夹中添加单元测试用例。测试语法基于 [Jest](https://jestjs.io/) 和 [Vitest](https://vitest.dev/)。
+
+### 运行单元测试
+
+在提交 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 jest copy-assets
+```
+
+---
+
+## Linting
+
+为了帮助保持代码风格的一致性和可读性，我们使用 ESLint 对代码进行校验。
+
+你可以执行以下命令来运行 Linter：
+
+```sh
+pnpm run lint
+```
+
+---
+
+## 文档
+
+目前 Modern.js 提供英文和中文文档。如果你熟悉中文，请同时更新中英文文档。否则，只需更新英文文档即可。
+
+你可以在 `packages/document` 文件夹中找到所有文档：
+
+```sh
+root
+└─ packages
+   └─ document
+       ├─ builder-doc    # Modern.js Builder 文档
+       ├─ doc-tools-doc  # Modern.js Doc 文档
+       ├─ main-doc       # Modern.js Framework 文档
+       └─ module-doc     # Modern.js Module 文档
+```
+
+文档站使用 [Modern.js Doc](https://modernjs.dev/doc-tools) 构建，文档内容可以使用 markdown 或 mdx 语法编写。详细使用方法可以参考 [Modern.js Doc 文档](https://modernjs.dev/doc-tools)。
+
+Modern.js Doc 的源代码可以在 [这个文件夹](https://github.com/web-infra-dev/modern.js/tree/main/packages/solutions/doc-tools) 中找到。
+
+---
+
+## 提交变更
+
+### 添加 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/about/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/about/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/about/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/configure/app/output/disable-svgr.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: disableSvgr
+---
+
+# output.disableSvgr
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [output.disableSvgr](https://modernjs.dev/builder/api/config-output.html#outputdisablesvgr)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/output/disableSvgr.md';
+
+<Main />

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

@@ -31,7 +31,9 @@ MODERN_ENV 的优先级高于 NODE_ENV。
 
 ### MODERN_TARGET
 
-使用 `@modern-js/runtime` 时会自动注入，用于区分 SSR 与 CSR 环境。开发者可以自行在代码中判断，构建时会默认移除 dead code。
+使用 `@modern-js/runtime` 时，Modern.js 会自动注入 `MODERN_TARGET`，用于区分 SSR 与 CSR 环境。
+
+你可以在代码中通过 `process.env.MODERN_TARGET` 来判断环境，并执行相应的逻辑。
 
 ```ts title="App.tsx"
 function App() {
@@ -41,9 +43,10 @@ function App() {
 }
 ```
 
-开发环境打包后，可以看到 SSR 产物和 CSR 产物如下：
+在开发环境构建完成后，可以看到 SSR 产物和 CSR 产物如下：
 
 ```js title="dist/bundles/main.js"
+// SSR 产物
 function App() {
   if (false) {
   }
@@ -51,6 +54,7 @@ function App() {
 ```
 
 ```js title="dist/static/main.js"
+// CSR 产物
 function App() {
   if (true) {
     console.log(window.innerHeight);
@@ -58,12 +62,17 @@ function App() {
 }
 ```
 
-:::note
-在生产环境，会将 dead code 移除，例如上述 `if` 语句。
+这种方式可以针对不同客户端提供不同的产物，保证代码体积最小化；也便于处理不同环境下代码中的一些副作用。
+
+:::note 死代码移除
+在生产环境，Terser 和 SWC 等代码压缩工具会分析代码，并将 dead code 移除，从而减少产物体积，这个过程被称为死代码移除（DCE）。
+
+例如，上述 `if (false)` 语句包含的代码会被移除，而 `if (true)` 包含的代码将被保留。
+
+如果你未按照上述写法来使用 `process.env.MODERN_TARGET`，代码压缩工具可能会无法分析出 dead code，从而导致产物体积增大。
 
 :::
 
-这种方式可以针对不同客户端提供不同的产物，保证代码体积最小化。也能方便处理不同环境下，代码中的一些副作用，
 
 ## 自定义环境变量
 

package/docs/zh/guides/troubleshooting/dependencies.mdx

@@ -18,8 +18,8 @@ sidebar_position: 1
 
 ```
 project
-└─┬ @modern-js/app-tools@1.6.10
-  └── @modern-js/core@1.12.4
+└─┬ @modern-js/app-tools@2.0.0
+  └── @modern-js/core@2.0.0
 ```
 
 **pnpm**
@@ -30,8 +30,8 @@ project
 
 ```
 devDependencies:
-@modern-js/app-tools 1.7.0
-└── @modern-js/core 1.13.0
+@modern-js/app-tools 2.0.0
+└── @modern-js/core 2.0.0
 ```
 
 ---
@@ -88,7 +88,7 @@ Type '{}' is not assignable to type 'ReactNode'.
 }
 ```
 
-关于锁定依赖版本的方法，请参考上方的 `如何锁定项目中的某个依赖版本？`。
+关于锁定依赖版本的方法，请参考 [锁定子依赖](/guides/get-started/upgrade.html#锁定子依赖)。
 
 ---
 
@@ -97,3 +97,14 @@ Type '{}' is not assignable to type 'ReactNode'.
 出现该警告的原因是，某些三方 npm 包声明的 peer dependencies 版本范围与 Modern.js 中安装的版本范围不一致。
 
 绝大多数情况下，peer dependencies 的警告不会影响项目运行，不需要额外进行处理，请忽略相关 warning。
+
+---
+
+### Modern.js 框架最低支持的 React 版本是多少？
+
+**Modern.js 框架推荐使用的 React 版本为 >= 18.0.0**，并且不同功能对 React 版本的要求有所不同。
+
+- 如果你在使用 React 17，那么部分框架功能将无法使用，比如 Steaming SSR，因为它依赖 React 18 提供的新特性。
+- 如果你仍然在使用 React 16，那么将无法使用 Modern.js 的运行时或服务端能力。你可以考虑使用 Modern.js 的构建模式，即只使用 Modern.js 的构建能力，这种情况是可以继续使用 React 16 的。
+
+在 Modern.js 未来的 major 版本中，我们会逐步移除对 React 16 和 React 17 的支持。因此，请尽快升级到 React 18 以上版本。

package/modern.config.ts

@@ -8,6 +8,7 @@ const rootCategories = [
   'apis/app',
   'configure/app',
   'blog',
+  'about',
 ];
 
 const { version } = require('./package.json');
@@ -45,6 +46,11 @@ const getNavbar = (lang: string): NavItem[] => {
       link: getLink('/blog/index'),
       activeMatch: '/blog/',
     },
+    {
+      text: getText('关于', 'About'),
+      link: getLink('/about/showcase'),
+      activeMatch: '/about/',
+    },
     {
       text: `v${version}`,
       items: [

package/package.json

@@ -3,7 +3,11 @@
   "description": "Documentation of modern.js framework",
   "homepage": "https://modernjs.dev",
   "bugs": "https://github.com/web-infra-dev/modern.js/issues",
-  "repository": "web-infra-dev/modern.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/web-infra-dev/modern.js",
+    "directory": "packages/document/main-doc"
+  },
   "license": "MIT",
   "keywords": [
     "react",
@@ -11,13 +15,13 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.14.0",
+  "version": "2.16.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.14.0"
+    "@modern-js/builder-doc": "^2.16.0"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -29,9 +33,9 @@
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.14.0",
-    "@modern-js/doc-tools": "2.14.0",
-    "@modern-js/doc-plugin-auto-sidebar": "2.14.0"
+    "@modern-js/builder-doc": "2.16.0",
+    "@modern-js/doc-tools": "2.16.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.16.0"
   },
   "scripts": {
     "dev": "modern dev",

package/src/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["@modern-js-app"]
+}

package/src/components/RandomMemberList/index.module.scss

@@ -0,0 +1,35 @@
+.wrapper {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+}
+
+.link {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-direction: column;
+  width: 20%;
+  max-width: 20%;
+  margin: 24px 0;
+
+  &:hover {
+    .avatar {
+      transform: scale(1.15);
+    }
+  }
+}
+
+.avatar {
+  width: 48px;
+  height: 48px;
+  border-radius: 999px;
+  transition: all 0.2s ease-in-out;
+  background-color: #f8f8f8;
+}
+
+.name {
+  margin-top: 12px;
+  font-size: 13px;
+  color: rgb(0, 53, 67);
+}

package/src/components/RandomMemberList/index.tsx

@@ -0,0 +1,122 @@
+import { NoSSR } from '@modern-js/doc-tools/runtime';
+import style from './index.module.scss';
+
+interface Member {
+  id: string;
+  avatar: string;
+  // The display name, if not set, use id instead
+  name?: string;
+}
+
+const MEMBERS: Member[] = [
+  {
+    id: '10Derozan',
+    avatar: 'https://avatars.githubusercontent.com/u/50694858?s=120&v=4',
+  },
+  {
+    id: '2heal1',
+    avatar: 'https://avatars.githubusercontent.com/u/41466093?s=120&v=4',
+  },
+  {
+    id: '9aoy',
+    avatar: 'https://avatars.githubusercontent.com/u/22373761?s=120&v=4',
+  },
+  {
+    id: 'Asuka109',
+    avatar: 'https://avatars.githubusercontent.com/u/18379948?s=120&v=4',
+  },
+  {
+    id: 'caohuilin',
+    avatar: 'https://avatars.githubusercontent.com/u/12605189?s=120&v=4',
+  },
+  {
+    id: 'chenjiahan',
+    avatar: 'https://avatars.githubusercontent.com/u/7237365?s=120&v=4',
+  },
+  {
+    id: 'clChenLiang',
+    avatar: 'https://avatars.githubusercontent.com/u/13596193?s=120&v=4',
+  },
+  {
+    id: 'danpeen',
+    avatar: 'https://avatars.githubusercontent.com/u/18045417?s=120&v=4',
+  },
+  {
+    id: 'GiveMe-A-Name',
+    avatar: 'https://avatars.githubusercontent.com/u/58852732?s=120&v=4',
+  },
+  {
+    id: 'jkzing',
+    avatar: 'https://avatars.githubusercontent.com/u/2851517?s=120&v=4',
+  },
+  {
+    id: 'JSerFeng',
+    avatar: 'https://avatars.githubusercontent.com/u/57202839?s=120&v=4',
+  },
+  {
+    id: 'KyrieLii',
+    avatar: 'https://avatars.githubusercontent.com/u/16858738?s=120&v=4',
+  },
+  {
+    id: 'nyqykk',
+    avatar: 'https://avatars.githubusercontent.com/u/65393845?s=120&v=4',
+  },
+  {
+    id: 'sanyuan0704',
+    avatar: 'https://avatars.githubusercontent.com/u/39261479?s=120&v=4',
+  },
+  {
+    id: 'targeral',
+    avatar: 'https://avatars.githubusercontent.com/u/9037723?s=120&v=4',
+  },
+  {
+    id: 'xuchaobei',
+    avatar: 'https://avatars.githubusercontent.com/u/5110783?s=120&v=4',
+  },
+  {
+    id: 'xyoscer',
+    avatar: 'https://avatars.githubusercontent.com/u/16360717?s=120&v=4',
+  },
+  {
+    id: 'yimingjfe',
+    avatar: 'https://avatars.githubusercontent.com/u/10381581?s=120&v=4',
+  },
+  {
+    id: 'zhoushaw',
+    avatar: 'https://avatars.githubusercontent.com/u/27547179?s=120&v=4',
+  },
+  {
+    id: 'zllkjc',
+    avatar: 'https://avatars.githubusercontent.com/u/68810266?s=120&v=4',
+  },
+  {
+    id: 'zoolsher',
+    avatar: 'https://avatars.githubusercontent.com/u/9161085?s=120&v=4',
+  },
+];
+
+export const RandomMemberList = () => {
+  const randomList = MEMBERS.sort(() => Math.random() - 0.5);
+
+  return (
+    <NoSSR>
+      <div className={style.wrapper}>
+        {randomList.map(item => (
+          <a
+            className={style.link}
+            href={`https://github.com/${item.id}`}
+            target="_blank"
+            rel="nofollow"
+            key={item.id}
+            style={{
+              border: 'none',
+            }}
+          >
+            <img className={style.avatar} src={item.avatar} />
+            <span className={style.name}>{item.name || item.id}</span>
+          </a>
+        ))}
+      </div>
+    </NoSSR>
+  );
+};