@modern-js/main-doc 2.42.1 → 2.43.0

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

@@ -4,9 +4,87 @@ sidebar_position: 4
 
 # 路径别名
 
-import Alias from '@modern-js/builder-doc/docs/zh/shared/alias';
+路径别名（alias）允许开发者为模块定义别名，以便于在代码中更方便的引用它们。当你想要使用一个简短、易于记忆的名称来代替冗长复杂的路径时，这将非常有用。
 
-<Alias />
+例如，假如你在项目中经常引用 `src/common/request.ts` 模块，你可以为它定义一个别名 `@request`，然后在代码中通过 `import request from '@request'` 来引用它，而不需要每次都写出完整的相对路径。同时，这也允许你将模块移动到不同的位置，而不需要更新代码中的所有 import 语法。
+
+在 Modern.js 中，你有两种方式可以设置路径别名:
+
+- 通过 `tsconfig.json` 中的 `paths` 配置。
+- 通过 [source.alias](/configure/app/source/alias) 配置。
+
+## 通过 `tsconfig.json` 的 `paths` 配置
+
+你可以通过 `tsconfig.json` 中的 `paths` 来配置别名，这是我们在 TypeScript 项目中推荐使用的方式，因为它可以解决路径别名的 TS 类型问题。
+
+比如：
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "paths": {
+      "@common/*": ["./src/common/*"]
+    }
+  }
+}
+```
+
+以上配置完成后，如果你在代码中引用 `@common/Foo.tsx`, 则会映射到 `<project>/src/common/Foo.tsx` 路径上。
+
+:::tip
+你可以阅读 [TypeScript - paths](https://www.typescriptlang.org/tsconfig#paths) 文档来了解更多用法。
+:::
+
+## 通过 `source.alias` 配置
+
+Modern.js 提供了 [source.alias](/configure/app/source/alias) 配置项，对应 webpack / Rspack 原生的 [resolve.alias](https://webpack.js.org/configuration/resolve/#resolvealias) 配置，你可以通过对象或者函数的方式来配置这个选项。
+
+### 使用场景
+
+由于 `tsconfig.json` 的 `paths` 配置是写在静态 JSON 文件里的，因此它不具备动态性。
+
+而 `source.alias` 则可以弥补这一不足，你可以通过 JavaScript 代码来动态设置 `source.alias`（比如基于环境变量来设置）。
+
+### 对象用法
+
+你可以通过对象的方式来配置 `source.alias`，其中的相对路径会被自动补全为绝对路径。
+
+比如：
+
+```js
+export default {
+  source: {
+    alias: {
+      '@common': './src/common',
+    },
+  },
+};
+```
+
+以上配置完成后，如果你在代码中引用 `@common/Foo.tsx`, 则会映射到 `<project>/src/common/Foo.tsx` 路径上。
+
+### 函数用法
+
+你也可以将 `source.alias` 配置为一个函数，拿到内置的 `alias` 对象，对其进行修改。
+
+比如：
+
+```js
+export default {
+  source: {
+    alias: alias => {
+      alias['@common'] = './src/common';
+      return alias;
+    },
+  },
+};
+```
+
+### 优先级
+
+`tsconfig.json` 的 `paths` 配置的优先级高于 `source.alias`，当一个路径同时匹配到这两者定义的规则时，会优先使用 `tsconfig.json` 的 `paths` 定义的值。
+
+你可以通过 [source.aliasStrategy](/configure/app/source/alias-strategy) 来调整这两个选项的优先级。
 
 ## 默认别名
 

package/docs/zh/guides/basic-features/css-modules.mdx

@@ -0,0 +1,229 @@
+---
+sidebar_position: 14
+---
+
+# 使用 CSS Modules
+
+[CSS Modules](https://github.com/css-modules/css-modules) 让我们能以模块化的方式编写 CSS 代码，并且可以在 JavaScript 文件中导入和使用这些样式。使用 CSS Modules 可以自动生成唯一的类名，隔离不同模块之间的样式，避免类名冲突。
+
+Builder 默认支持使用 CSS Modules，无需添加额外的配置。我们约定使用 `[name].module.css` 文件名来启用 CSS Modules。
+
+以下样式文件会被视为 CSS Modules：
+
+- `*.module.scss`
+- `*.module.less`
+- `*.module.css`
+
+## 示例
+
+- 编写样式：
+
+```css
+/* button.module.css */
+.error {
+  background: red;
+}
+```
+
+- 使用样式：
+
+```tsx
+// Button.tsx
+import React, { Component } from 'react';
+// 引入样式文件
+import styles from './button.module.css';
+
+export default () => {
+  return <button className={styles.error}>Error Button</button>;
+};
+```
+
+## 为所有样式文件启用 CSS Modules
+
+在默认情况下，只有 `*.module.css` 结尾的文件才被视为 CSS Modules 模块。
+
+如果你想将源码目录下的所有 CSS 文件当做 CSS Modules 模块进行处理，可以通过开启 [output.disableCssModuleExtension](/configure/app/output/disable-css-module-extension) 来实现，比如：
+
+```ts
+export default {
+  output: {
+    disableCssModuleExtension: true,
+  },
+};
+```
+
+设置后，以下两个文件都会被视为 CSS Modules：
+
+```ts
+import styles1 from './foo.module.css';
+import styles2 from './bar.css';
+```
+
+:::tip
+我们不推荐开启此配置项，因为开启 `disableCssModuleExtension` 后，CSS Modules 文件和普通 CSS 文件无法得到明确的区分，不利于长期维护。
+:::
+
+## 为指定的样式文件启用 CSS Modules
+
+在默认情况下，只有 `*.module.css` 结尾的文件才被视为 CSS Modules 模块。
+
+如果你想只为一些指定的样式文件启用 CSS Modules，可以通过配置 [output.cssModules](/configure/app/output/css-modules) 来实现，比如：
+
+```ts
+export default {
+  output: {
+    cssModules: {
+      auto: resource => {
+        return resource.includes('.module.') || resource.includes('shared/');
+      },
+    },
+  },
+};
+```
+
+## 自定义类名
+
+自定义 CSS Modules 生成的类名也是我们比较常用的功能，你可以使用 [output.cssModuleLocalIdentName](/configure/app/output/css-modules.html#cssmodulesexportlocalsconvention) 来进行配置。
+
+```ts
+export default {
+  output: {
+    cssModuleLocalIdentName: '[hash:base64:4]',
+  },
+};
+```
+
+如果你需要自定义 CSS Modules 的其他配置，可以通过 [tools.cssLoader](/configure/app/tools/css-loader) 进行设置。
+
+## 添加类型声明
+
+当你在 TypeScript 代码中引用 CSS Modules 时，TypeScript 可能会提示该模块缺少类型定义：
+
+```
+TS2307: Cannot find module './index.module.css' or its corresponding type declarations.
+```
+
+此时你需要为 CSS Modules 添加类型声明文件，请在项目中创建 `src/global.d.ts` 文件，并添加相应的类型声明：
+
+```ts title="src/global.d.ts"
+declare module '*.module.css' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.scss' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.sass' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.less' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.styl' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+```
+
+如果你开启了 `disableCssModuleExtension` 配置值，还需要添加以下类型：
+
+```ts title="src/global.d.ts"
+declare module '*.css' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.scss' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.sass' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.less' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.styl' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+```
+
+添加类型声明后，如果依然存在上述错误提示，请尝试重启当前 IDE，或者调整 `global.d.ts` 所在的目录，使 TypeScript 能够正确识别类型定义。
+
+## 生成准确的类型定义
+
+上述方法虽然可以解决 CSS Modules 在 TypeScript 中的类型问题，但是无法准确地提示出某个 CSS 文件导出了哪些类名。
+
+Builder 支持为 CSS Modules 生成准确的类型声明，你只需要开启 [output.enableCssModuleTSDeclaration](/configure/app/output/enable-css-module-tsdeclaration) 配置项，再执行构建命令，Builder 就会为项目中所有的 CSS Modules 文件生成相应的类型声明文件。
+
+```ts
+export default {
+  output: {
+    enableCssModuleTSDeclaration: true,
+  },
+};
+```
+
+### 示例
+
+例如某个文件夹下面有 `src/index.ts` 和 `src/index.module.scss` 两个文件：
+
+```tsx title="src/index.ts"
+import styles from './index.module.scss';
+
+export default () => {
+  <div>
+    <div className={styles.pageHeader}>Page Header</div>
+  </div>;
+};
+```
+
+```scss
+// index.module.scss
+.page-header {
+  color: black;
+}
+```
+
+执行构建命令后，会自动生成 `src/index.module.scss.d.ts` 类型声明文件：
+
+```ts title="src/index.module.scss.d.ts"
+// This file is automatically generated.
+// Please do not change this file!
+interface CssExports {
+  'page-header': string;
+  pageHeader: string;
+}
+export const cssExports: CssExports;
+export default cssExports;
+```
+
+此时再打开 `src/index.ts` 文件，可以看到 `styles` 对象已经具备了准确的类型。
+
+### 相关配置
+
+在上述例子中，`src/index.module.scss.d.ts` 是编译生成的代码，你可以选择将它们提交到 Git 仓库里，也可以选择在 `.gitignore` 文件中忽略它们：
+
+```bash
+# Ignore auto generated CSS declarations
+*.module.css.d.ts
+*.module.sass.d.ts
+*.module.scss.d.ts
+*.module.less.d.ts
+*.module.styl.d.ts
+```
+
+此外，如果生成的代码导致了 ESLint 报错，你也可以将上述配置添加到 `.eslintignore` 文件里。

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

@@ -22,7 +22,7 @@ Modern.js 内置了 [PostCSS](https://postcss.org/) 来转换 CSS 代码。
 
 ## 使用 CSS Modules
 
-请阅读 [使用 CSS Modules](https://modernjs.dev/builder/guide/basic/css-modules.html) 章节来了解 CSS Modules 的完整用法。
+请阅读 [使用 CSS Modules](/guides/basic-features/css-modules) 章节来了解 CSS Modules 的完整用法。
 
 ## 使用 CSS-in-JS
 
@@ -72,18 +72,7 @@ Modern.js 内部集成了 Babel 的 [babel-plugin-styled-components](https://git
 ? 请选择功能名称 启用 「Tailwind CSS」 支持
 ```
 
-成功开启后，会看到 `package.json` 中新增了依赖：
-
-```json title="./package.json"
-{
-  "dependencies": {
-    "tailwindcss": "^3.0.0"
-  },
-  "devDependencies": {
-    "@modern-js/plugin-tailwindcss": "^2.0.0"
-  }
-}
-```
+成功开启后，你会看到 `package.json` 中新增了 `tailwindcss` 和 `@modern-js/plugin-tailwindcss` 依赖。
 
 2. 在 `modern.config.ts` 中注册 Tailwind 插件:
 

package/docs/zh/guides/basic-features/data/data-write.mdx

@@ -84,7 +84,7 @@ Modern.js 中提供 Data Action 主要是为了使 UI 和服务器的状态能
 ![state manage](https://lf3-static.bytednsdoc.com/obj/eden-cn/ulkl/ljhwZthlaukjlkulzlp/action-state-manage1.png)
 
 如果项目中组件共享的数据主要服务端的状态，则无需在项目引入客户端状态管理库，使用 Data Loader 请求数据，通过 [`useRouteLoaderData`](/guides/basic-features/data/data-fetch.md) 在子组件中共享数据，
-通过 Data Actino 修改和同步服务端的状态。
+通过 Data Action 修改和同步服务端的状态。
 
 
 

package/docs/zh/guides/basic-features/json-files.mdx

@@ -0,0 +1,106 @@
+---
+sidebar_position: 12
+---
+
+# 引用 JSON 文件
+
+Modern.js 支持在代码中引用 JSON 文件，也支持引用 [YAML](https://yaml.org/) 和 [TOML](https://toml.io/en/) 文件并将其转换为 JSON 格式。
+
+## JSON 文件
+
+你可以直接在 JavaScript 文件中引用 JSON 文件。
+
+### 示例
+
+```json title="example.json"
+{
+  "name": "foo",
+  "items": [1, 2]
+}
+```
+
+```js title="index.js"
+import example from './example.json';
+
+console.log(example.name); // 'foo';
+console.log(example.items); // [1, 2];
+```
+
+### 具名引用
+
+Modern.js 暂不支持通过 named import 来引用 JSON 文件：
+
+```js
+import { name } from './example.json';
+```
+
+## YAML 文件
+
+YAML 是一种数据序列化语言，通常用于编写配置文件。
+
+你可以直接在 JavaScript 中引用 `.yaml` 或 `.yml` 文件，它们会被自动转换为 JSON 格式。
+
+### 示例
+
+```yaml title="example.yaml"
+---
+hello: world
+foo:
+  bar: baz
+```
+
+```js
+import example from './example.yaml';
+
+console.log(example.hello); // 'world';
+console.log(example.foo); // { bar: 'baz' };
+```
+
+### 添加类型声明
+
+当你在 TypeScript 代码中引用 YAML 文件时，请在项目中创建 `src/global.d.ts` 文件，并添加相应的类型声明：
+
+```ts title="src/global.d.ts"
+declare module '*.yaml' {
+  const content: Record<string, any>;
+  export default content;
+}
+
+declare module '*.yml' {
+  const content: Record<string, any>;
+  export default content;
+}
+```
+
+## TOML 文件
+
+TOML 是一种语义明显、易于阅读的配置文件格式。
+
+你可以直接在 JavaScript 中引用 `.toml` 文件，它会被自动转换为 JSON 格式。
+
+### 示例
+
+```toml title="example.toml"
+hello = "world"
+
+[foo]
+bar = "baz"
+```
+
+```js
+import example from './example.toml';
+
+console.log(example.hello); // 'world';
+console.log(example.foo); // { bar: 'baz' };
+```
+
+### 添加类型声明
+
+当你在 TypeScript 代码中引用 TOML 文件时，请在项目中创建 `src/global.d.ts` 文件，并添加相应的类型声明：
+
+```ts title="src/global.d.ts"
+declare module '*.toml' {
+  const content: Record<string, any>;
+  export default content;
+}
+```

package/docs/zh/guides/basic-features/output-files.mdx

@@ -0,0 +1,173 @@
+---
+sidebar_position: 10
+---
+
+# 构建产物目录
+
+本章节主要介绍构建产物的目录结构，以及如何控制不同类型产物的输出目录。
+
+## 默认产物目录
+
+下面是最基础的产物目录结构，默认情况下，构建产物会生成在当前项目的 `dist` 目录下。
+
+```bash
+dist
+├── static
+│   ├── css
+│   │   ├── [name].[hash].css
+│   │   └── [name].[hash].css.map
+│   │
+│   └── js
+│       ├── [name].[hash].js
+│       ├── [name].[hash].js.LICENSE.txt
+│       └── [name].[hash].js.map
+│
+└── html
+    └── [name]
+        └── index.html
+```
+
+最常见的产物是 HTML 文件、JS 文件和 CSS 文件：
+
+- HTML 文件：默认输出到 `html` 目录。
+- JS 文件：默认输出到 `static/js` 目录，
+- CSS 文件：默认输出到 `static/css` 目录。
+
+此外，JS 文件和 CSS 文件有时候会生成一些相关产物：
+
+- License 文件：包含开源许可证信息，默认输出到 JS 文件的同级目录，并添加 `.LICENSE.txt` 后缀。
+- Source Map 文件：包含保存源代码映射关系，默认输出到 JS 文件和 CSS 文件的同级目录，并添加 `.map` 后缀。
+
+在产物的文件名称中，`[name]` 表示这个文件对应的入口名称，比如 `index`, `main`。`[hash]` 则是基于该文件的内容生成的哈希值。
+
+## 修改产物目录
+
+Builder 提供了多个配置项来修改产物目录和产物名称，你可以：
+
+- 通过 [output.filename](/configure/app/output/filename) 来修改产物的文件名。
+- 通过 [output.distPath](/configure/app/output/dist-path) 来修改产物的输出路径。
+- 通过 [output.legalComments](/configure/app/output/legal-comments) 来修改 License 文件的生成方式。
+- 通过 [output.disableSourceMap](/configure/app/output/disable-source-map) 来移除 Source Map 文件。
+- 通过 [html.disableHtmlFolder](/configure/app/html/disable-html-folder) 移除 HTML 产物对应的文件夹。
+
+## 静态资源
+
+当你在代码中引用图片、SVG、字体、媒体等类型的静态资源时，它们也会被输出到 `dist/static` 目录下，并根据静态资源类型来自动分配到对应的子目录：
+
+```bash
+dist
+└── static
+    ├── image
+    │   └── foo.[hash].png
+    │
+    ├── svg
+    │   └── bar.[hash].svg
+    │
+    ├── font
+    │   └── baz.[hash].woff2
+    │
+    └── media
+        └── qux.[hash].mp4
+```
+
+你可以通过 [output.distPath](/configure/app/output/dist-path) 配置项将这些静态资源统一输入到单个目录下，比如输出到 `assets` 目录：
+
+```ts
+export default {
+  output: {
+    distPath: {
+      image: 'assets',
+      svg: 'assets',
+      font: 'assets',
+      media: 'assets',
+    },
+  },
+};
+```
+
+上方的配置会生成以下目录结构：
+
+```bash
+dist
+└── assets
+    ├── foo.[hash].png
+    ├── bar.[hash].svg
+    ├── baz.[hash].woff2
+    └── qux.[hash].mp4
+```
+
+## Node.js 产物目录
+
+当你在 Modern.js 中开启了 SSR 或 SSG 等服务端功能时，Modern.js 会在构建后生成一份 Node.js 产物，并输出到 `bundles` 目录下：
+
+```bash
+dist
+├── bundles
+│   └── [name].js
+├── static
+└── html
+```
+
+Node.js 产物通常只包含 JS 文件，不包含 HTML、CSS 等文件。此外，Node 产物的 JS 文件名称也不会自动生成哈希值。
+
+你可以通过 [output.distPath.server](/configure/app/output/dist-path) 配置项来修改 Node 产物的输出路径。
+
+比如，将 Node.js 产物输出到 `server` 目录：
+
+```ts
+export default {
+  output: {
+    distPath: {
+      server: 'server',
+    },
+  },
+};
+```
+
+## 扁平化产物目录
+
+有时候你不想产物目录有太多层级，可以将目录设置为空字符串，使生成的产物目录扁平化。
+
+参考下方的例子：
+
+```ts
+export default {
+  output: {
+    distPath: {
+      js: '',
+      css: '',
+      html: '',
+    },
+  },
+  html: {
+    disableHtmlFolder: true,
+  },
+};
+```
+
+上方的配置会生成以下目录结构：
+
+```bash
+dist
+├── [name].[hash].css
+├── [name].[hash].css.map
+├── [name].[hash].js
+├── [name].[hash].js.map
+└── [name].html
+```
+
+## 产物不写入磁盘
+
+默认情况下，Builder 会将构建产物写入磁盘，以方便开发者查看产物的内容，或是配置静态资源的代理规则。
+
+在开发环境，你可以选择将构建产物保存在 Dev Server 的内存中，从而减少文件操作产生的开销。
+
+将 `dev.writeToDisk` 配置项设置为 `false` 即可：
+
+```ts
+export default {
+  dev: {
+    writeToDisk: false,
+  },
+};
+```