@modern-js/main-doc 2.42.0 → 2.42.2

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

package/docs/zh/guides/basic-features/static-assets.mdx

@@ -0,0 +1,165 @@
+---
+sidebar_position: 10
+---
+
+# 引用静态资源
+
+Modern.js 支持在代码中引用图片、字体、媒体类型的静态资源。
+
+:::tip 什么是静态资源
+静态资源是指 Web 应用中不会发生变化的文件。常见的静态资源包括图片、字体、视频、样式表和 JavaScript 文件。这些资源通常存储在服务器或 CDN 上，当用户访问 Web 应用时会被传送到用户的浏览器。由于它们不会发生变化，静态资源可以被浏览器缓存，从而提高 Web 应用的性能。
+:::
+
+## 静态资源格式
+
+以下是 Modern.js 默认支持的静态资源格式：
+
+- **图片**：png、jpg、jpeg、gif、svg、bmp、webp、ico、apng、avif、tiff。
+- **字体**：woff、woff2、eot、ttf、otf、ttc。
+- **媒体**：mp4、webm、ogg、mp3、wav、flac、aac、mov。
+
+如果你需要引用其他格式的静态资源，请参考 [扩展静态资源类型](#扩展静态资源类型)。
+
+:::tip SVG 图片
+SVG 图片是一种特殊情况，Modern.js 提供了 SVG 转 React 组件的能力，对 SVG 进行单独处理，详见 [引用 SVG 资源](/guides/basic-features/svg-assets.html)。
+:::
+
+## 在 JS 文件中引用
+
+在 JS 文件中，可以直接通过 `import` 的方式引用相对路径下的静态资源：
+
+```tsx
+// 引用 static 目录下的 logo.png 图片
+import logo from './static/logo.png';
+
+export default = () => <img src={logo} />;
+```
+
+也支持使用[路径别名](/guides/basic-features/alias.html)来引用：
+
+```tsx
+import logo from '@/static/logo.png';
+
+export default = () => <img src={logo} />;
+```
+
+## 在 CSS 文件中引用
+
+在 CSS 文件中，可以引用相对路径下的静态资源：
+
+```css
+.logo {
+  background-image: url('../static/logo.png');
+}
+```
+
+也支持使用[路径别名](/guides/basic-features/alias.html)来引用：
+
+```css
+.logo {
+  background-image: url('@/static/logo.png');
+}
+```
+
+## 引用结果
+
+引用静态资源的结果取决于文件体积：
+
+- 当文件体积大于 10KB 时，会返回一个 URL，同时文件会被输出到构建产物目录下。
+- 当文件体积小于 10KB 时，会自动被内联为 Base64 格式。
+
+```js
+import largeImage from './static/largeImage.png';
+import smallImage from './static/smallImage.png';
+
+console.log(largeImage); // "/static/largeImage.6c12aba3.png"
+console.log(smallImage); // "data:image/png;base64,iVBORw0KGgo..."
+```
+
+关于资源内联的更详细介绍，请参考 [静态资源内联](/guides/advanced-features/inline-assets) 章节。
+
+## 构建产物
+
+当静态资源被引用后，会自动被输出到构建产物的目录下，你可以：
+
+- 通过 [output.filename](/configure/app/output/filename) 来修改产物的文件名。
+- 通过 [output.distPath](/configure/app/output/dist-path) 来修改产物的输出路径。
+
+请阅读 [构建产物目录](/guides/basic-features/output-files) 来了解更多细节。
+
+## URL 前缀
+
+引用静态资源后返回的 URL 中会自动包含路径前缀：
+
+- 在开发环境下，通过 [dev.assetPrefix](/configure/app/dev/asset-prefix) 设置路径前缀。
+- 在生产环境下，通过 [output.assetPrefix](/configure/app/output/asset-prefix) 设置路径前缀。
+
+比如将 `output.assetPrefix` 设置为 `https://modern.com`：
+
+```js
+import logo from './static/logo.png';
+
+console.log(logo); // "https://modern.com/static/logo.6c12aba3.png"
+```
+
+## 添加类型声明
+
+当你在 TypeScript 代码中引用静态资源时，TypeScript 可能会提示该模块缺少类型定义：
+
+```
+TS2307: Cannot find module './logo.png' or its corresponding type declarations.
+```
+
+此时你需要为静态资源添加类型声明文件，请在项目中创建 `src/global.d.ts` 文件，并添加相应的类型声明。以 png 图片为例，需要添加以下声明：
+
+```ts title="src/global.d.ts"
+declare module '*.png' {
+  const content: string;
+  export default content;
+}
+```
+
+添加类型声明后，如果依然存在上述错误提示，请尝试重启当前 IDE，或者调整 `global.d.ts` 所在的目录，使 TypeScript 能够正确识别类型定义。
+
+## 扩展静态资源类型
+
+如果 Modern.js 内置的静态资源类型不能满足你的需求，那么你可以通过 [tools.bundlerChain](/configure/app/tools/bundler-chain) 来修改内置的 webpack / Rspack 配置，并扩展你需要的静态资源类型。
+
+比如，你需要把 `*.pdf` 文件当做静态资源直接输出到产物目录，可以添加以下配置：
+
+```ts
+export default {
+  tools: {
+    bundlerChain(chain) {
+      chain.module
+        .rule('pdf')
+        .test(/\.pdf$/)
+        .type('asset/resource');
+    },
+  },
+};
+```
+
+添加以上配置后，你就可以在代码里引用 `*.pdf` 文件了，比如：
+
+```js
+import myFile from './static/myFile.pdf';
+
+console.log(myFile); // "/static/myFile.6c12aba3.pdf"
+```
+
+关于以上配置的更多介绍，请参考：
+
+- [Rspack 文档 - Asset modules](https://www.rspack.dev/guide/asset-module.html#asset-modules)
+- [webpack 文档 - Asset modules](https://webpack.js.org/guides/asset-modules/)
+
+## 图片格式
+
+在使用图片资源时，你可以根据下方表格中图片的优缺点以及适用场景，来选择合适的图片格式。
+
+| 格式 | 优点                                                             | 缺点                                   | 适用场景                                                                     |
+| ---- | ---------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| PNG  | 无损压缩，不会丢失图片细节，不失真，支持半透明                   | 不适合色表复杂的图片                   | 适合颜色数量少，边界层次分明的图片，适合用在 logo、icon、透明图等场景        |
+| JPG  | 颜色丰富                                                         | 有损压缩，会导致图片失真，不支持透明度 | 适合颜色数量多，颜色带有渐变、过度复杂的图片，适合用在人像照片、风景图等场景 |
+| WebP | 同时支持有损压缩与无损压缩，支持透明度，体积比 PNG 和 JPG 小很多 | iOS 兼容性不好                         | 几乎任何场景的像素图片，支持 WebP 的宿主环境，都应该首选 WebP 图片格式       |
+| SVG  | 无损格式，不失真,支持透明度                                      | 不适合复杂图形                         | 适合矢量图,适合用于 icon                                                     |

package/docs/zh/guides/basic-features/svg-assets.mdx

@@ -0,0 +1,157 @@
+---
+sidebar_position: 11
+---
+
+# 引用 SVG 资源
+
+Modern.js 支持在代码中引用 SVG 资源，并将 SVG 图片转换为 React 组件或 URL。
+
+:::tip 什么是 SVG
+SVG 是 Scalable Vector Graphics 的缩写，意为可伸缩矢量图形。SVG 是一种用来描述二维矢量图形的 XML-based 格式，可以用来创建可以无限放大或缩小而不失真的图像。因为 SVG 图形是由矢量图形元素组成的，所以可以轻松地在各种尺寸和分辨率下渲染。
+:::
+
+## 在 JS 文件中引用
+
+在 JS 文件中引用 SVG 资源时，如果你具名导入 `ReactComponent` 对象，Modern.js 会调用 [SVGR](https://react-svgr.com/)，将 SVG 图片转换为一个 React 组件。
+
+```tsx title="src/component/Logo.tsx"
+import { ReactComponent as Logo } from './static/logo.svg';
+
+export default () => <Logo />;
+```
+
+如果你使用默认导入，那么 SVG 会被当做普通的静态资源来处理，你会得到一个 URL 字符串：
+
+```tsx title="src/component/Logo.tsx"
+import logoURL from './static/logo.svg';
+
+console.log(logoURL); // => "/static/logo.6c12aba3.png"
+```
+
+## 修改默认导出
+
+你可以通过 [output.svgDefaultExport](/configure/app/output/svg-default-export) 配置项来修改 SVG 文件默认导出的内容，比如把默认导出的内容设置为 React 组件：
+
+```ts
+export default {
+  output: {
+    svgDefaultExport: 'component',
+  },
+};
+```
+
+此时再使用默认导入，你会得到一个 React 组件，而不是 URL：
+
+```tsx title="src/component/Logo.tsx"
+import Logo from './static/logo.svg';
+
+export default () => <Logo />;
+```
+
+## 在 CSS 文件中引用
+
+在 CSS 文件中引用 SVG 资源时，SVG 会被当做一个普通的静态资源来处理，你会得到一个 URL：
+
+```css
+.logo {
+  background-image: url('../static/logo.svg');
+}
+```
+
+## 静态资源处理
+
+当 SVG 不是作为 React 组件，而是作为一个普通的静态资源被引用时，它的处理逻辑和其他静态资源完全一致，也会受到静态资源内联、URL 前缀等规则的影响。
+
+请阅读 [引用静态资源](/guides/basic-features/static-assets) 章节来了解静态资源的处理规则。
+
+## 禁用 SVGR 处理
+
+默认情况下，在 JS 文件中引用 SVG 资源时，Modern.js 会调用 SVGR，将 SVG 图片转换为一个 React 组件。
+
+如果你确定项目内的所有 SVG 资源都没有当成 React 组件使用时，可以通过将 [disableSvgr](/configure/app/output/disable-svgr) 设置为 true 来关闭此项转换，以提升构建性能。
+
+```js
+export default {
+  output: {
+    disableSvgr: true,
+  },
+};
+```
+
+## 添加类型声明
+
+当你在 TypeScript 代码中引用 SVG 资源时，TypeScript 可能会提示该模块缺少类型定义：
+
+```
+TS2307: Cannot find module './logo.svg' or its corresponding type declarations.
+```
+
+此时你需要为 SVG 资源添加类型声明文件，请在项目中创建 `src/global.d.ts` 文件，并添加相应的类型声明：
+
+```ts
+declare module '*.svg' {
+  export const ReactComponent: React.FunctionComponent<
+    React.SVGProps<SVGSVGElement>
+  >;
+
+  const content: string;
+  export default content;
+}
+```
+
+如果你将 `svgDefaultExport` 设置为 `'component'`，则将类型声明修改为：
+
+```ts
+declare module '*.svg' {
+  export const ReactComponent: React.FunctionComponent<
+    React.SVGProps<SVGSVGElement>
+  >;
+
+  export default ReactComponent;
+}
+```
+
+添加类型声明后，如果依然存在上述错误提示，请尝试重启当前 IDE，或者调整 `global.d.ts` 所在的目录，使 TypeScript 能够正确识别类型定义。
+
+## 修改 SVGR 配置
+
+当启用 SVGR 时，其默认配置如下：
+
+```js
+{
+  svgo: true,
+  svgoConfig: {
+    plugins: [
+      {
+        name: 'preset-default',
+        params: {
+          overrides: {
+            removeViewBox: false,
+          },
+        },
+      },
+      'prefixIds',
+    ],
+  },
+}
+```
+
+如果需要修改 SVGR 配置，可通过如下方式：
+
+```js
+export default {
+  tools: {
+    bundlerChain: (chain, { CHAIN_ID }) => {
+      chain.module
+        .rule(CHAIN_ID.RULE.SVG)
+        .oneOf(CHAIN_ID.ONE_OF.SVG)
+        .use(CHAIN_ID.USE.SVGR)
+        .tap(options => {
+          // modify svgoConfig
+          options.svgoConfig.plugins[0].params.overrides.removeUselessDefs = false;
+          return options;
+        });
+    },
+  },
+};
+```

package/docs/zh/guides/basic-features/wasm-assets.mdx

@@ -0,0 +1,66 @@
+---
+sidebar_position: 13
+---
+
+# 引用 Wasm 资源
+
+Modern.js 支持在代码引用 WebAssembly 资源。
+
+:::tip 什么是 WebAssembly
+WebAssembly（缩写为 wasm）是一种可移植、高性能的字节码格式，被设计用来在现代 Web 浏览器中执行 CPU 密集型计算任务，为 Web 平台带来了接近本地编译代码的性能和可靠性。
+:::
+
+## 引用方式
+
+你可以直接在 JavaScript 文件中引用一个 WebAssembly 模块：
+
+```js title="index.js"
+import { add } from './add.wasm';
+
+console.log(add); // [native code]
+console.log(add(1, 2)); // 3
+```
+
+也可以通过 dynamic import 来引用 WebAssembly 模块：
+
+```js title="index.js"
+import('./add.wasm').then(({ add }) => {
+  console.log('---- Async Wasm Module');
+  console.log(add); // [native code]
+  console.log(add(1, 2)); // 3
+});
+```
+
+还可以通过 `new URL` 语法来获取 WebAssembly 模块的路径：
+
+```js title="index.js"
+const wasmURL = new URL('./add.wasm', import.meta.url);
+
+console.log(wasmURL).pathname; // "/static/wasm/[hash].module.wasm"
+```
+
+## 输出目录
+
+当 `.wasm` 资源被引用后，默认会被 Modern.js 输出到 `dist/static/wasm` 目录下。
+
+你可以通过 [output.distPath](/configure/app/output/dist-path) 配置项来修改 `.wasm` 产物的输出目录。
+
+```ts
+export default {
+  output: {
+    distPath: {
+      wasm: 'resource/wasm',
+    },
+  },
+};
+```
+
+## 添加类型声明
+
+当你在 TypeScript 代码中引用 Wasm 文件时，通常需要添加相应的类型声明。
+
+比如 `add.wasm` 文件导出了 `add()` 方法，那么你可以在同级目录下创建一个 `add.wasm.d.ts` 文件，并添加相应的类型声明：
+
+```ts title="add.wasm.d.ts"
+export const add = (num1: number, num2: number) => number;
+```

package/docs/zh/guides/get-started/quick-start.mdx

@@ -116,7 +116,7 @@ dist
     └── js
 ```
 
-> 如果你需要自定义构建产物的目录，请参考 [构建产物目录](https://modernjs.dev/builder/guide/basic/output-files.html)。
+> 如果你需要自定义构建产物的目录，请参考 [构建产物目录](/guides/basic-features/output-files)。
 
 ## 本地验证
 

package/package.json

@@ -15,17 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.42.0",
+  "version": "2.42.2",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "2.42.0"
+    "@modern-js/sandpack-react": "2.42.2"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.42.0"
+    "@modern-js/builder-doc": "^2.42.2"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -35,12 +35,12 @@
     "ts-node": "^10.9.1",
     "typescript": "^5",
     "fs-extra": "^10",
-    "rspress": "1.7.4",
-    "@rspress/shared": "1.7.4",
+    "rspress": "1.8.2",
+    "@rspress/shared": "1.8.2",
     "@types/node": "^16",
     "@types/fs-extra": "9.0.13",
-    "@modern-js/doc-plugin-auto-sidebar": "2.42.0",
-    "@modern-js/builder-doc": "2.42.0"
+    "@modern-js/doc-plugin-auto-sidebar": "2.42.2",
+    "@modern-js/builder-doc": "2.42.2"
   },
   "scripts": {
     "dev": "rspress dev",