@modern-js/main-doc 2.8.0 → 2.10.0

package/docs/zh/guides/advanced-features/compatibility.mdx

@@ -0,0 +1,77 @@
+---
+title: 客户端兼容性
+sidebar_position: 5
+---
+# 客户端兼容性
+
+## Browserslist 配置
+
+Modern.js 支持在项目根目录 `package.json` 文件中的 `browserslist` 字段（或单独的 `.browserslistrc` 文件）指定项目覆盖的目标浏览器范围。该值会被 [`@babel/preset-env`](https://babeljs.io/docs/en/babel-preset-env) 和 [`autoprefixer`](https://github.com/postcss/autoprefixer) 用来确定需要转换的 JavaScript 语法特性和需要添加的 CSS 浏览器前缀。
+
+Modern.js 中默认值如下:
+
+```js
+['> 0.01%', 'not dead', 'not op_mini all'];
+```
+
+可以在[这里](https://github.com/browserslist/browserslist)了解如何自定义浏览器范围。
+
+查看 Modern.js Builder 文档了解更多 [Browserslist](https://modernjs.dev/builder/guide/advanced/browserslist.html) 相关内容。
+
+:::note
+Modern.js 支持配置 [output.overrideBrowserslist](/configure/app/output/override-browserslist) 覆盖默认 browserslist 值。
+
+:::
+
+## Polyfill
+
+### 编译时 Polyfill
+
+Modern.js 在编译时默认通过 [core-js](https://github.com/zloirock/core-js) 引入对应的 Polyfill 代码。
+
+默认情况下会根据项目 Browserslist 的设置情况引入所需的 Polyfill 代码， 这样基本不用再担心项目源码和第三方依赖的 Polyfill 问题了，但是因为包含了一些没有用到的 Polyfill 代码，所以最终的包大小可能会有所增加。
+
+:::info
+对于明确第三方依赖不需要 Polyfill 的场景，可以设置 [`output.polyfill`](/configure/app/output/polyfill) 为 `usage`, 这样 Babel 编译时只会根据代码中使用到的语法引入 Polyfill 代码。
+
+:::
+
+### 运行时按需 Polyfill
+
+Modern.js 中还提供了基于浏览器 [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) 信息的运行时按需 Polyfill 方案，相比于 Babel 优势如下：
+
+- 不会插入到代码中，只根据访问页面的设备，按需下发 Polyfill 代码 ，减少整体代码体积。
+- 相同浏览器会公用一份 Polyfill 代码。因此，随着项目越来越多，基于 UA 的 Polyfill 代码下发速度会越来越快，综合速度超过常规方案。
+
+可以通过微生成器开启该功能：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「基于 UA 的 Polyfill」功能
+```
+
+执行命令后，在 `modern.config.ts` 中注册 Polyfill 插件:
+
+```ts title="modern.config.ts"
+import polyfillPlugin from '@modern-js/plugin-polyfill';
+
+export default defineConfig({
+  plugins: [..., polyfillPlugin()],
+});
+```
+
+配置 `output.polyfill` 为 `ua` 并且执行 `pnpm run build && pnpm run serve` 启动服务器后，访问页面可以看到 HTML 产物中包含如下脚本:
+
+```js
+<script src="/__polyfill__" crossorigin></script>
+```
+
+在 Chrome 51 下访问页面可以看到 `http://localhost:8080/__polyfill__` 返回内容如下:
+
+![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
+
+:::caution 注意
+该功能只有在使用 Modern.js 内置的 Web Server 时才会生效。
+
+如果有自定义模版的需求，请参考 [HTML 模板](/guides/basic-features/html.html)。通过 `html.template` 或 `tools.html` 手动修改模版时，可能会导致该功能无法正确生效。
+:::

package/docs/zh/guides/advanced-features/eslint.mdx

@@ -0,0 +1,152 @@
+---
+title: ESLint 规则集
+sidebar_position: 8
+---
+# ESLint 规则集
+
+{/* 参考 [实战教程 - 确认编程环境](../handbook/c03-ide/3.1-setting-up) 确保本地 IDE 环境正常。  */}
+
+**Modern.js ESLint 规则集**是全量的 **ESLint** 规则集合，包含 `@modern-js` （对于 Node.js 项目的 Lint 规则）和 `@modern-js-app`（对于前端项目的 Lint 规则）。
+
+下面以具体问题介绍更多 ESLint 用法。
+
+## Q: 如何处理 Lint
+
+### 实时自动修复
+
+多数问题会被 ESLint 规则的自动修复功能或 [Prettier](https://prettier.io/) 的代码格式化功能（已被集成到 ESLint 里）自动解决，开发者不需要关心问题的细节和解决方式。
+
+:::info
+主要在 IDE 保存文件的环节执行这种自动修复，少数漏网之鱼会在提交代码环节被自动修复。
+
+:::
+
+### 批量自动修复
+
+在少数情况下，比如旧项目迁移的时候，可以执行以下命令，批量修复和检查所有文件：
+
+```bash
+pnpm run lint:error
+```
+
+### 人工修复
+
+对于无法自动修复的问题，可以在 IDE 里点击问题提示框里的规则链接，打开这条规则的文档，查看问题的解释和解决方案。
+
+### 声明例外情况
+
+目前阶段，有些规则并不能做到足够智能，多数情况下会有很大收益，在少数情况下也许不适用。但如果为了这些少数情况就把整个规则关掉或改掉，得不偿失。
+
+这种情况下可以用 [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) 注释，对符合**少数情况**的代码块做标注，声明这里是一个例外，应该忽略。比如：
+
+```js
+/* eslint-disable filenames/match-exported */
+...
+/* eslint-enable filenames/match-exported */
+```
+
+:::info
+在 VS Code 编辑器里输入 eslint，会自动出现关于 "eslint-disable" 的提示框，选择提示选项生成对应注释对。
+
+:::
+
+【Modern.js ESLint 规则集】要求 [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) 必须成对使用，必须明确表达要影响的范围，以及在这个范围内明确表达要禁用什么规则，目的是让**例外**有明确的、最小化的范围，避免 [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) 被滥用，导致不属于例外的代码也被禁用了规则。
+
+## Q: 如何自定义 ESLint 规则
+
+### 仓库根目录下 `package.json` 里的 "eslintConfig" 字段
+
+这个地方是整个仓库的默认 ESLint 配置，是针对纯 Node.js 代码（只能在 Node.js 里运行）设计的。
+
+如果项目在某些规则上确实有特殊要求或不可避免的兼容问题（不是例外），可以在这里增加规则配置。该配置会优先于默认的【Modern.js ESLint 规则集】，比如：
+
+```json
+ "eslintConfig": {
+    "extends": [
+      "@modern-js"
+    ],
+    "rules": {
+      "filenames/match-exported": "off"
+    }
+  },
+
+```
+
+### `src/.eslintrc.js` 文件
+
+Modern.js 的应用工程、模块工程，源代码目录里都会默认有这个配置文件，是针对 Universal JS 代码设计的。
+
+:::info
+Universal JS 代码是既能浏览器端也能在服务器端运行的代码。
+
+:::
+
+如果项目在某些规则上确实有特殊要求或不可避免的兼容问题（不是例外），可以在这里增加规则配置，该配置会优先于默认的【Modern.js ESLint 规则集】，比如：
+
+```js
+// eslint-disable-next-line import/no-commonjs
+module.exports = {
+  root: true,
+  extends: ['@modern-js-app'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: ['../tsconfig.json'],
+  },
+  rules: {
+    'filenames/match-exported': 'off',
+  },
+};
+```
+
+如果有需要，还可以继续在不同的子目录里增加 `.eslintrc.js` 文件，针对这个子目录里的代码做特殊配置：
+
+```js
+module.exports = {
+  rules: {
+    'filenames/match-exported': 'off',
+  },
+};
+```
+
+:::tip 提示
+注意：没有必要使用 `extends` 字段，会自动继承父目录的配置。
+
+:::
+
+### package.json 里的 `eslintIgnore` 字段
+
+把包含 `.js`、`.jsx`、`.ts`、`.tsx` 文件、但不需要做代码检查和自动修复的目录，添加到 `eslintIgnore` 里，可以优化 ESLint 检查的速度，比如：
+
+```json
+ "eslintIgnore": [
+    "node_modules",
+    "dist",
+    "output"
+  ],
+```
+
+## Q: 如何升级 ESLint 插件的版本
+
+只要不是 Major 版本的变化（不符合 [Semver](https://semver.org/) 规则的 `^` 符号），就可以直接在业务项目的 `package.json` 里指定这个依赖，删除 Lock 文件（或尝试手动删除 Lock 文件中这个包名的内容），执行 `pnpm install` 重新安装依赖并且生成新的 Lock 文件。
+
+做完这些操作之后，在业务项目的 `./node_modules` 目录里，这个插件应该只存在一份，并且升级到了你指定的版本。
+
+:::tip 提示
+- Major 版本就是主版本号。更多信息，请阅读 [Semantic Versioning](https://semver.org/#summary)。
+- 所有被 Modern.js 封装的上游项目（比如 ESLint、[ESLint 插件](https://eslint.org/docs/user-guide/configuring/plugins#plugins)、[React Router](https://reactrouter.com/) 等），也都可以这样升级。
+- Modern.js 也会在每次发版中尽量及时的升级这些上游依赖。
+- Major 版本的升级需要由 Modern.js 来发版。
+
+:::
+
+## Q: WebStorm 有时候会报 ESLint 错误
+
+由于 WebStorm 认为 ESLint 执行目录是根据 `.eslintrc` 文件来决定的。因此 `src/.eslintrc` 文件位置的放置会导致 `tsconfig.json` 文件指定的位置（项目根目录下）在 `src/` 目录下找不到。
+
+此时需要手动配置一下：
+
+```json
+--parser-options=project:../tsconfig.json
+```
+
+![webstorm-lint-error](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/webstorm-lint-error.png)

package/docs/zh/guides/advanced-features/rspack-start.mdx

@@ -0,0 +1,62 @@
+---
+title: 使用 Rspack
+sidebar_position: 1
+---
+
+# 使用 Rspack
+
+import Rspack from '@modern-js/builder-doc/docs/zh/shared/rspack-tip.mdx';
+
+<Rspack />
+
+**Modern.js 提供开箱即用的 Rspack 支持**，你可以在成熟的 Webpack 和更快的 Rspack 之间进行切换。
+
+这篇文档会向你介绍如何在 Modern.js 中开启 Rspack 构建模式。
+
+## 初始化 Rspack 项目
+
+Modern.js 生成器会提供一个可交互的问答界面，只需将构建工具选择为 **Rspack**，即可创建一个 Rspack 项目:
+
+import InitRspackApp from '@site-docs/components/init-rspack-app';
+
+<InitRspackApp />
+
+项目创建完成后，在项目中执行 `pnpm run dev` 即可体验项目，更多信息可参考[快速上手](/guides/get-started/quick-start.html)。
+
+:::tip
+在使用 Rspack 作为打包工具时，由于部分能力尚在开发中，以下 features 暂时无法使用，我们将在未来提供支持：
+
+- 微前端（Micro Frontend）
+- Storybook 调试
+- 同时使用服务端渲染（SSR）和约定式路由的场景
+- 同时使用静态站点生成（SSG）和约定式路由的场景
+
+:::
+
+## 从 webpack 迁移至 Rspack
+
+在一个已有的 Modern.js 项目中，你可以通过执行 `pnpm run new` 来启用 Rspack 构建：
+
+```bash
+$ pnpm run new
+? 请选择你想要的操作：启用可选功能
+? 启用可选功能：启用「Rspack 构建」
+```
+
+执行以上命令后，在 `modern.config.ts` 中添加 Rspack 相关配置即可：
+
+```diff title=modern.config.ts
+import appTools, { defineConfig } from '@modern-js/app-tools';
+
++ export default defineConfig<'rspack'>({
+  plugins: [
+    appTools({
++     bundler: 'experimental-rspack',
+    }),
+  ],
+});
+```
+
+:::tip
+从 webpack 迁移至 Rspack 时，存在一些构建能力和配置上的差异，详情可参考：[配置差异](https://modernjs.dev/builder/guide/advanced/rspack-start.html#从-webpack-迁移到-rspack)
+:::