@modern-js/main-doc 2.42.1 → 2.42.2

package/docs/zh/guides/advanced-features/inline-assets.mdx

@@ -0,0 +1,162 @@
+---
+sidebar_position: 13
+---
+
+# 静态资源内联
+
+静态资源内联是一种优化网页性能的方法，它指的是将静态资源直接内联到 HTML 或 JS 文件中，而不是使用外部文件引用的方式。这样做的好处是减少了浏览器发起的请求数，从而提高页面的加载速度。
+
+不过，静态资源内联也有一些缺点，比如增加了单个文件的体积，可能会导致加载变慢。所以在实际应用中，需要根据具体情况来决定是否使用静态资源内联。
+
+Modern.js 默认会自动内联体积小于 10KB 的静态资源，但有时候你可能需要手动控制某些特殊资源，让其强制内联或者强制不内联，这篇文档阐述了如何进行精确地控制静态资源内联行为。
+
+## 自动内联
+
+默认情况下，当图片、字体、媒体等类型的文件体积小于阈值（默认为 10KB）时，Modern.js 会将资源进行内联处理，资源内联后，会被转换成一个 Base64 编码的字符串，不再会发送独立的 HTTP 请求。当文件体积大于或等于该阈值时，则会被作为单独的资源文件，通过独立的 HTTP 请求来加载。
+
+自动内联的体积阈值可以通过 [output.dataUriLimit](/configure/app/output/data-uri-limit) 配置项修改。例如，修改图片资源的阈值为 5000 字节，设置视频资源不内联：
+
+```ts
+export default {
+  output: {
+    dataUriLimit: {
+      image: 5000,
+      media: 0,
+    },
+  },
+};
+```
+
+## 强制内联
+
+你可以通过在引入资源时添加 `inline` URL 参数来强制内联该资源，无论该资源的体积是否小于阈值。
+
+```tsx
+import React from 'react';
+import img from './foo.png?inline';
+
+export default function Foo() {
+  return <img src={img} />;
+}
+```
+
+在上面这个例子中，`foo.png` 图片将始终被内联，无论该图片的大小是否大于阈值。
+
+除了 `inline` 参数以外，你也可以使用 `__inline` 参数来强制内联该资源：
+
+```tsx
+import img from './foo.png?__inline';
+```
+
+### 从 CSS 文件中引用
+
+当你在 CSS 文件中引用静态资源时，同样可以通过 `inline` 或 `__inline` 参数来强制内联资源。
+
+```css
+.foo {
+  background-image: url('./icon.png?inline');
+}
+```
+
+:::tip 你真的需要强制内联吗？
+内联体积过大的资源时，会显著增加页面的白屏时间或首次可交互时间，这会损害用户体验。并且当你将一个静态资源多次内联到 CSS 文件中时，base64 内容会重复注入，导致产物体积增大。因此，请酌情使用强制内联。
+:::
+
+## 强制不内联
+
+当你想把一些资源始终作为单独的资源文件来处理，无论该资源的体积多小时，你可以添加 `url` URL 参数来强制不内联该资源。
+
+```tsx
+import React from 'react';
+import img from './foo.png?url';
+
+export default function Foo() {
+  return <img src={img} />;
+}
+```
+
+在上面这个例子中，`foo.png` 图片将始终通过单独的资源文件加载，无论该图片的大小是否小于阈值。
+
+除了 `url` 参数以外，你也可以使用 `__inline=false` 参数来强制不内联该资源：
+
+```tsx
+import img from './foo.png?__inline=false';
+```
+
+### 从 CSS 文件中引用
+
+当你在 CSS 文件中引用静态资源时，同样可以通过 `url` 或 `__inline=false` 参数来强制不内联资源。
+
+```css
+.foo {
+  background-image: url('./icon.png?url');
+}
+```
+
+:::tip 你真的需要把资源排除内联吗？
+将资源排除内联将增加 Web App 需要加载的资源数量，这对于弱网环境，或是未开启 HTTP2 的场景下，将会降低资源加载效率，因此，请酌情使用强制不内联。
+:::
+
+## 内联 JS 文件
+
+除了将静态资源文件内联到 JS 文件里，Modern.js 也支持将 JS 文件内联到 HTML 文件中。
+
+只需要开启 [output.enableInlineScripts](/configure/app/output/enable-inline-scripts) 配置项，构建生成的 JS 文件将不会被写入产物目录下，而是会直接内联到对应的 HTML 文件中。
+
+```ts
+export default {
+  output: {
+    enableInlineScripts: true,
+  },
+};
+```
+
+:::tip
+内联 JS 文件可能会导致 HTML 单文件体积过大，并且不利于静态资源缓存，请酌情使用。
+:::
+
+## 内联 CSS 文件
+
+你也可以将 CSS 文件内联到 HTML 文件中。
+
+只需要开启 [output.enableInlineStyles](/configure/app/output/enable-inline-styles) 配置项，构建生成的 CSS 文件将不会被写入产物目录下，而是会直接内联到对应的 HTML 文件中。
+
+```ts
+export default {
+  output: {
+    enableInlineStyles: true,
+  },
+};
+```
+
+## 添加类型声明
+
+当你在 TypeScript 代码中使用 `?inline` 和 `?url` 等 URL 参数时，TypeScript 可能会提示该模块缺少类型定义：
+
+```
+TS2307: Cannot find module './logo.png?inline' or its corresponding type declarations.
+```
+
+此时你需要为这些 URL 参数添加类型声明，请在项目中创建 `src/global.d.ts` 文件，并添加以下类型声明：
+
+```ts
+declare module '*?inline' {
+  const content: string;
+  export default content;
+}
+
+declare module '*?inline' {
+  const content: string;
+  export default content;
+}
+
+declare module '*?__inline' {
+  const content: string;
+  export default content;
+}
+
+declare module '*?inline=false' {
+  const content: string;
+  export default content;
+}
+```

package/docs/zh/guides/advanced-features/optimize-bundle.mdx

@@ -4,7 +4,7 @@ sidebar_position: 13
 
 # 产物体积优化
 
-产物体积的优化在生产环境中是非常重要的，因为它直接影响到了线上的用户体验。在这篇文档中，我们将介绍在 Builder 中一些常见的产物体积优化方式。
+产物体积的优化在生产环境中是非常重要的，因为它直接影响到了线上的用户体验。在这篇文档中，我们将介绍在 Modern.js 中一些常见的产物体积优化方式。
 
 ## 减少重复依赖
 
@@ -82,13 +82,14 @@ export default {
 
 ## 使用图片压缩
 
-在一般的前端项目中，图片资源的体积往往是项目产物体积的大头，因此如果能尽可能精简图片的体积，那么将会对项目的打包产物体积起到明显的优化效果。你可以在 Builder 中注册插件来启用图片压缩功能:
+在一般的前端项目中，图片资源的体积往往是项目产物体积的大头，因此如果能尽可能精简图片的体积，那么将会对项目的打包产物体积起到明显的优化效果。你可以在 Modern.js 中注册插件来启用图片压缩功能:
 
-```js
+```js title="modern.config.ts"
 import { builderPluginImageCompress } from '@modern-js/builder-plugin-image-compress';
 
-// 往 builder 实例上添加插件
-builder.addPlugins([builderPluginImageCompress()]);
+export default {
+  builderPlugins: [builderPluginImageCompress()],
+};
 ```
 
 详见 [Image Compress 插件](https://modernjs.dev/builder/plugins/plugin-image-compress.html)。
@@ -97,7 +98,7 @@ builder.addPlugins([builderPluginImageCompress()]);
 
 良好的拆包策略对于提升应用的加载性能是十分重要的，可以充分利用浏览器的缓存机制，减少请求数量，加快页面加载速度。
 
-在 Builder 中内置了[多种拆包策略](https://modernjs.dev/builder/guide/optimization/split-chunk)，可以满足大部分应用的需求，你也可以根据自己的业务场景，自定义拆包配置。
+在 Modern.js 中内置了[多种拆包策略](https://modernjs.dev/builder/guide/optimization/split-chunk)，可以满足大部分应用的需求，你也可以根据自己的业务场景，自定义拆包配置。
 
 比如将 node_modules 下的 `axios` 库拆分到 `axios.js` 中：
 

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/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;
+}
+```