@modern-js/main-doc 2.42.1 → 2.43.0

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/docs/zh/guides/get-started/tech-stack.mdx

@@ -97,7 +97,7 @@ Modern.js 支持 [Sass](https://sass-lang.com/)、[Less](https://lesscss.org/)
 
 Modern.js 对 [CSS Modules](https://github.com/css-modules/css-modules) 提供了开箱即用的支持，内部基于 [css-loader](https://www.npmjs.com/package/css-loader) 实现。
 
-请参考[「使用 CSS Modules」](https://modernjs.dev/builder/guide/basic/css-modules.html) 来使用。
+请参考[「使用 CSS Modules」](/guides/basic-features/css-modules) 来使用。
 
 ---
 

package/docs/zh/guides/topic-detail/framework-plugin/introduction.mdx

@@ -6,29 +6,74 @@ sidebar_position: 1
 
 ## Modern.js 插件系统
 
-Modern.js 用于扩展项目运行、请求、渲染等不同阶段功能的系统，主要分为三个部分：Hook 模型、管理器，上下文共享机制。
+Modern.js 提供了一套拥有完整生命周期的插件系统。插件可用于扩展项目运行、请求、渲染等不同阶段功能，
 
-Hook 模型用于确定当前 Hook 的执行方式，不同 Hook 模型的函数拥有不同的执行逻辑。管理器用于控制 Hook 的执行与调度。上下文共享机制用于在不同 Hook 间传递信息。
+## 使用方式
 
-目前 Modern.js 提供几种不同的 Hook 模型：
+插件需要在配置文件中显示注册才能够生效，当需要为 Modern.js 添加插件时，可以将它配置到 [plugin](/configure/app/plugins.html) 字段中：
 
-- Pipeline
-  - Sync
-  - Async
-- Waterfall
-  - Sync
-  - Async
-- Workflow
-  - Sync
-  - Async
-  - Parallel(Async)
+```ts title="edenx.config.ts"
+// an example for bff
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { bffPlugin } from '@modern-js/plugin-bff';
+
+export default defineConfig({
+  plugins: [appTools(), bffPlugin()],
+});
+```
 
 :::note
-后续章节详细介绍各个模型的执行方式。
+注意，该配置仅支持添加 Modern.js 插件，无法添加 Webpack 插件。
+:::
+
+## 官方插件
+
+Modern.js 提供了一系列官方插件，并与 Modern.js 生成器结合。所有的官方插件功能，都可以通过执行 `new` 命令开启。例如当需要开启 BFF 功能时：
+
+```bash
+$ npx modern new
+? 请选择你想要的操作 启用可选功能
+? 请选择功能名称 (Use arrow keys)
+  启用 「Tailwind CSS」 支持
+❯ 启用「BFF」功能
+  启用「微前端」模式
+  启用「单元测试 / 集成测试」功能
+  启用「Visual Testing (Storybook)」模式
+```
+
+完成选择后，Modern.js 生成器会自动安装对应的插件和三方依赖，安装完成后可以看到：
+
+```bash
+[INFO] 依赖自动安装成功
+
+[INFO] 安装插件依赖成功！请添加如下代码至 modern.config.ts :
 
+import { bffPlugin } from '@modern-js/plugin-bff';
+import { expressPlugin } from '@modern-js/plugin-express';
+
+export default defineConfig({
+  ...,
+  plugins: [..., bffPlugin(), expressPlugin()],
+});
+```
+
+此时，可以按照控制台的输出，将插件添加到配置文件中。
+
+## 插件系统组成
+
+Modern.js 插件系统主要分为三个部分：Hook 模型、管理器，上下文共享机制。
+
+- Hook 模型用于确定当前 Hook 的执行逻辑。
+- 管理器用于控制 Hook 的执行与调度。
+- 上下文共享机制用于在不同 Hook 间传递信息。
+
+目前 Modern.js 提供几种不同的 Hook 模型：**Pipeline、Waterfall、Workflow**。
+
+:::note
+后续章节详细介绍各个模型的执行方式。
 :::
 
-基于 Hook 模型和管理器，Modern.js 暴露了三套插件：CLI、Runtime、Server。
+Modern.js 基于 Hook 模型暴露了三套插件：CLI、Runtime、Server。
 
 其中 CLI 插件是 Modern.js 中主要的运行流程控制模型，Modern.js 中绝大部分功能都是主要通过这一套模型运行的。Runtime 插件主要负责处理 React 组件渲染逻辑。Server 插件主要用于对服务端的生命周期以及用户请求的控制。
 
@@ -48,4 +93,4 @@ Modern.js 的所有功能都是通过这套插件实现的，这意味着 Modern
 - 自定义 React 组件客户端/服务器端渲染
 - ...
 
-当 Modern.js 暂时没有覆盖到你所需要的功能或场景时，可以开发一个自定义插件，来实现适配特殊场景的相关功能。
+当 Modern.js 暂时没有覆盖到所需要的功能或场景时，可以开发一个自定义插件，来实现适配特殊场景的相关功能。

package/package.json

@@ -15,17 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.42.1",
+  "version": "2.43.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "2.42.1"
+    "@modern-js/sandpack-react": "2.43.0"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.42.1"
+    "@modern-js/builder-doc": "^2.43.0"
   },
   "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.3",
+    "@rspress/shared": "1.8.3",
     "@types/node": "^16",
     "@types/fs-extra": "9.0.13",
-    "@modern-js/builder-doc": "2.42.1",
-    "@modern-js/doc-plugin-auto-sidebar": "2.42.1"
+    "@modern-js/builder-doc": "2.43.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.43.0"
   },
   "scripts": {
     "dev": "rspress dev",