npm - @modern-js/main-doc - Versions diffs - 2.59.0 → 2.60.0 - Mend

@modern-js/main-doc 2.59.0 → 2.60.0

Files changed (113) hide show

package/docs/en/guides/advanced-features/eslint.mdx DELETED Viewed

@@ -1,148 +0,0 @@
----
-sidebar_position: 8
----
-# ESLint Rules
-**Modern.js ESLint Rules** is the full set of **ESLint** rules, includes `@modern-js` (Lint rules for Node.js projects) and `@modern-js-app` (Lint rules for web projects).
-More ESLint usage is described below with specific questions.
-## Q: How To Deal With Lint
-### Automatic Fix
-Most problems will be solved by the automatic fix of ESLint rules or the code formatting of [Prettier](https://prettier.io/) (which has been integrated into ESLint), and the developer does not need to care about the details of the problem and how to solve it.
-:::info
-This kind of automatic fix is mainly performed when the IDE saves the file, and a few will be automatically fix on submit.
-:::
-### Batch Automatic Fix
-In rare cases, such as when an old project is migrated, the following commands can be executed to repair and inspect all files in bulk:
-```bash
-pnpm run lint:error
-```
-### Manual Fix
-For problems that cannot be automatically fixed, you can click the rule link in the problem prompt box in the IDE to open the document of this rule to view the explanation and solution of the problem.
-### Claim Exceptions
-At this stage, some rules are not smart enough, and in most cases there will be great benefits, and in a few cases it may not apply. But if the entire rule is turned off or changed for these few cases, the gain is not worth the loss.
-In this case, you can use the [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) comment to mark the code blocks that meet the **rare case**, stating that this is an exception and should be ignored. For example:
-```js
-/* eslint-disable filenames/match-exported */
-...
-/* eslint-enable filenames/match-exported */
-```
-:::info
-Enter eslint in the VS Code editor, a prompt box about `eslint-disable` will automatically appear, select the prompt option to generate the corresponding comment pair.
-:::
-[Modern.js ESLint Rule Set] requires that [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) must be used in pairs, the scope to be affected must be clearly expressed, and what rules to disable within this scope must be clearly expressed, the purpose is to make **exceptions** Clear, minimized scope to avoid abuse of [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules), resulting in code that does not belong to the exception being disabled by the rule.
-## Q: How to customize ESLint rules
-### The `eslintConfig` field in `package.json` in the root directory
-This place is the default ESLint configuration for the entire repository and is designed for pure Node.js code (which can only run in Node.js).
-If the project does have special requirements or inevitable compatibility issues with some rules (not exceptions), you can add rule configuration here. This configuration will take precedence over the default [Modern.js ESLint ruleset], such as:
-```json
- "eslintConfig": {
-    "extends": [
-      "@modern-js"
-    ],
-    "rules": {
-      "filenames/match-exported": "off"
-    }
-  },
-```
-### `src/.eslintrc.js`
-Modern.js Framework or Modern.js Module project will have this configuration file by default in the source code directory, which is designed for Universal JS code.
-:::info
-Universal JS code is code that can run on both the browser side and the server side.
-:::
-If the project does have special requirements or inevitable compatibility issues with some rules (not exceptions), you can add a rule configuration here, which will take precedence over the default [Modern.js ESLint ruleset], such as:
-```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',
-  },
-};
-```
-If necessary, you can continue to add the `.eslintrc.js` file in different subdirectories, and make special configuration for the code in this subdirectory:
-```js
-module.exports = {
-  rules: {
-    'filenames/match-exported': 'off',
-  },
-};
-```
-:::tip
-Note: It is not necessary to use the `extends` field, it will automatically inherit the configuration of the parent directory.
-:::
-### `eslintIgnore` field in `package.json`
-Adding directories that contain `.js`, `.jsx`, `.ts`, `.tsx` files, but do not require code inspection and automatic repair, to `eslintIgnore` can optimize the speed of ESLint inspection, such as:
-```json
- "eslintIgnore": [
-    "node_modules",
-    "dist",
-    "output"
-  ],
-```
-## Q: How to upgrade the version of the ESLint plugin
-As long as it is not a change in the Major version (the "^" symbol that does not comply with the [Semver](https://semver.org/) rule), you can specify this dependency directly in the `package.json` of the business project, delete the Lock file (or try to manually delete the Lock file). the contents of this package name in the file), execute `pnpm install` to reinstall the dependency and generate a new Lock file.
-After doing this, the plugin should only exist in the `./node_modules` directory of the business project and be upgraded to the version you specified.
-:::tip
-- Major version is the major version number. For more information, please read [[Semantic Versioning](https://semver.org/#summary) ].
-- All upstream projects encapsulated by Modern.js (such as ESLint, [ESLint plugin](https://eslint.org/docs/user-guide/configuring/plugins#plugins), [React Router](https://reactrouter.com/), etc.) can also be upgraded in this way.
-- Modern.js will also try to upgrade these upstream dependencies as timely as possible in each release.
-- Major version upgrades need to be published by Modern.js.
-:::
-## Q: WebStorm sometimes reports ESLint errors
-Since WebStorm believes that the ESLint execution directory is determined based on the `.eslintrc'` file. Therefore, the placement of the `src/.eslintrc` file location will cause the location specified by the `tsconfig.json` file (in the project root directory) to not be found in the'src/'directory.
-you need to configure it manually:
-```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/apis/app/hooks/api/api.mdx DELETED Viewed

@@ -1,81 +0,0 @@
----
-title: '**/*.[tj]s'
-sidebar_position: 1
----
-# **/*.[tj]s
-在 [BFF 函数写法](/guides/advanced-features/bff/type.html#函数写法)下，声明 API 路由的文件。除了[某些约定文件](/apis/app/hooks/api/api#白名单)外，`api` 目录下的文件会被注册为接口的路由。
-:::info
-使用 `api` 目录需要开启 BFF 功能，需要在项目下执行 new 命令启用「BFF」功能。
-该文件支持使用 `js` 或 `ts` 语言，但必须使用 `esm` 语法导出函数。
-:::
-## 该文件约定路由如下：
-### 默认路由
-路由系统会将以 `index` 命名的文件会被映射到上一层目录。
-- `api/index.ts` -> `$BASENAME/`
-- `api/user/index.ts` -> `$BASENAME/user`
-### 嵌套路由
-路由系统也支持解析嵌套的文件，如果创建嵌套文件夹结构，文件仍会以相同方式自动解析路由。
-- `api/hello.ts` -> `$BASENAME/hello`
-- `api/user/list.ts` -> `$BASENAME/user/list`
-### 动态路由
-路由系统支持通过 `[]` 命名的文件目录生成动态路由。
-- `api/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
-- `api/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
-- `api/article/[id]/info.ts` -> `$BASENAME/article/:id/info`
-其中的 `$BASENAME` 可以在 `modern.config.js` 中进行配置，默认值为 `/api`。
-### 白名单
-默认 `api` 目录下所有文件都会当作 BFF 函数文件去解析，但同样我们也设置了白名单，这些文件不被被解析：
-- 命名以 `_` 开头的文件。例如：`_utils.ts`。
-- 命名以 `_` 开头的文件夹下所有文件。例如：`_utils/index.ts`、`_utils/cp.ts`。
-- 测试文件。例如：`foo.test.ts`。
-- TypeScript 类型文件。例如：`hello.d.ts`。
-- `node_module` 下的文件。
-## 函数定义
-除了上面的路由规则之外，代码中函数定义与导出也有相应的约定。
-函数通过具名导出，导出函数的名字为对应接口接受的 HTTP Method，即：
-```ts
-export const get = async () => {
-  return {
-    name: 'Modern.js',
-    desc: '现代 web 工程方案',
-  };
-};
-```
-这样导出函数，则会得到一个 `GET` 接口。
-Modern.js 工程中支持了 9 个 Method 定义，即：`GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`，即可以用这些 Method 作为函数导出的名字。
-名字是大小不敏感的，就是说，如果是 `GET`，写成 `get`、`Get`、`GEt`、`GET`，都可以准确识别。而默认导出，即 `export default xxx` 则会被映射为 `Get`。
-因为 `delete` 是 JavaScript 中的关键字，可以使用 `del` 或者 `DELETE` 代替。
-可以在一个文件中定义多个不同 Method 的函数，但如果定义多个相同 Method 的函数，则只有第一个会生效。
-:::info
-需要注意的是，定义的函数都应该是异步的，这个与函数调用时类型有关。
-:::

package/docs/zh/apis/app/hooks/api/app.mdx DELETED Viewed

@@ -1,12 +0,0 @@
----
-title: _app.[tj]s
-sidebar_position: 2
----
-# _app.[tj]s
-在 [BFF 函数写法](/guides/advanced-features/bff/type.html#函数写法)下，该文件可以为 BFF 函数添加前置中间件。
-:::note
-具体示例请参考 [hook](/apis/app/runtime/bff/hook)
-:::

package/docs/zh/guides/advanced-features/bff/type.mdx DELETED Viewed

@@ -1,46 +0,0 @@
----
-sidebar_position: 2
-title: 函数写法 & 框架写法
----
-# 函数写法 & 框架写法
-运行时框架支持也是 **BFF** 中重要的一环。Modern.js 支持通过插件扩展 BFF 的运行时框架，并提供了一系列内置插件，开发者可以直接使用对应框架的约定和生态。
-插件中兼容了这些框架大部分的规范，每一种框架都需要提供两类扩展写法 BFF 函数的方式，分别是**函数写法**和**框架写法**。
-:::note
-当前 `api/` 目录结构是否为框架写法由对应的插件决定，Modern.js 并不关心。
-:::
-## 函数写法
-当插件认为当前为函数写法时，必须支持在 `api/_app.ts` 中编写中间件，用来扩展 BFF 函数。
-Modern.js 会收集 `api/_app.ts` 中的中间件，并传递给插件，由插件将中间件注入运行时，例如：
-```ts
-import { hook } from '@modern-js/runtime/server';
-export default hook(({ addMiddleware }) => {
-  addMiddleware(myMiddleware);
-});
-```
-:::note
-不同插件的中间件的写法不一定相同，详情可见[运行时框架](/guides/advanced-features/bff/frameworks)。
-:::
-## 框架写法
-框架写法是一种使用框架结构来扩展 BFF 函数的方式。和函数写法相比，框架写法虽然能够利用更多框架的结构，在复杂场景下让整个 BFF Server 更加清晰，但也相的更加复杂，需要关心更多框架层面的内容。
-框架写法中，所有的 BFF 函数都需要写在 `api/lambda/` 目录下，并且无法使用钩子文件 `_app.[tj]s`。
-多数情况下，函数写法就能覆盖大多数 BFF 函数的定制需求。只有当你的项目服务端逻辑比较复杂，代码需要分层，或者需要使用更多框架的元素时，才需要使用框架写法。
-:::note
-不同插件框架写法的目录结构不一定相同，详情可见[运行时框架](/guides/advanced-features/bff/frameworks)。
-:::

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

@@ -1,152 +0,0 @@
----
-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 Framework、Modern.js Module 的源代码目录里都会默认有这个配置文件，是针对 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)