@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

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

@@ -0,0 +1,174 @@
+---
+sidebar_position: 11
+---
+
+# 引用 SVG 资源
+
+Modern.js 支持在代码中引用 SVG 资源，并将 SVG 图片转换为 React 组件或 URL。
+
+:::tip 什么是 SVG
+SVG 是 Scalable Vector Graphics 的缩写，意为可伸缩矢量图形。SVG 是一种用来描述二维矢量图形的 XML-based 格式，可以用来创建可以无限放大或缩小而不失真的图像。因为 SVG 图形是由矢量图形元素组成的，所以可以轻松地在各种尺寸和分辨率下渲染。
+:::
+
+## 在 JS 文件中引用
+
+### 默认导入
+
+如果你使用默认导入来引用 SVG，它会被当做静态资源来处理，你会得到一个 URL 字符串：
+
+```tsx title="src/component/Logo.tsx"
+import logoURL from './static/logo.svg';
+
+console.log(logoURL); // => "/static/logo.6c12aba3.png"
+```
+
+### 转换 React 组件
+
+在 JS 文件中引用 SVG 资源时，如果导入的路径包含 `?react` 后缀，Modern.js 会调用 SVGR，将 SVG 图片转换为一个 React 组件：
+
+```tsx title="src/component/Logo.tsx"
+import Logo from './logo.svg?react';
+
+export default () => <Logo />;
+```
+
+Modern.js 也支持以下用法，通过具名导入 `ReactComponent` 来转换 SVG 为 React 组件：
+
+```tsx title="src/component/Logo.tsx"
+import { ReactComponent as Logo } from './static/logo.svg';
+
+export default () => <Logo />;
+```
+
+## 修改默认导出
+
+你可以通过 [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;
+}
+
+declare module '*.svg?react' {
+  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
+  export default ReactComponent;
+}
+```
+
+如果你将 `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/static-assets/wasm-assets.mdx

@@ -0,0 +1,66 @@
+---
+sidebar_position: 13
+---
+
+# 引用 Wasm 资源
+
+Modern.js 支持在代码引用 WebAssembly 资源。
+
+:::tip 什么是 WebAssembly
+WebAssembly（缩写为 wasm）是一种可移植、高性能的字节码格式，被设计用来在现代 Web 浏览器中执行 CPU 密集型计算任务，为 Web 平台带来了接近本地编译代码的性能和可靠性。
+:::
+
+## 引用方式
+
+你可以在 JavaScript 文件中使用 named import 引用一个 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/basic-features/static-assets.mdx

@@ -0,0 +1,160 @@
+# 引用静态资源
+
+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/static-assets/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/page-performance/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) 来修改内置的 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://rspack.rs/guide/asset-module.html#asset-modules)
+
+## 图片格式
+
+在使用图片资源时，你可以根据下方表格中图片的优缺点以及适用场景，来选择合适的图片格式。
+
+| 格式 | 优点                                                             | 缺点                                   | 适用场景                                                                     |
+| ---- | ---------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| PNG  | 无损压缩，不会丢失图片细节，不失真，支持半透明                   | 不适合色表复杂的图片                   | 适合颜色数量少，边界层次分明的图片，适合用在 logo、icon、透明图等场景        |
+| JPG  | 颜色丰富                                                         | 有损压缩，会导致图片失真，不支持透明度 | 适合颜色数量多，颜色带有渐变、过度复杂的图片，适合用在人像照片、风景图等场景 |
+| WebP | 同时支持有损压缩与无损压缩，支持透明度，体积比 PNG 和 JPG 小很多 | iOS 兼容性不好                         | 几乎任何场景的像素图片，支持 WebP 的宿主环境，都应该首选 WebP 图片格式       |
+| SVG  | 无损格式，不失真，支持透明度                                     | 不适合复杂图形                         | 适合矢量图，适合用于 icon                                                    |

package/docs/zh/guides/basic-features/testing/_meta.json

@@ -0,0 +1 @@
+["playwright", "rstest", "vitest", "jest", "cypress"]

package/docs/zh/guides/basic-features/testing/cypress.mdx

@@ -0,0 +1,95 @@
+# Cypress
+
+Cypress 是一个用于 E2E 测试和组件测试的框架。
+
+在 Modern.js 中使用 Cypress 需要先安装依赖，可以执行以下命令：
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command={{ npm: "npm install -D cypress", yarn: "yarn add -D cypress", pnpm: "pnpm install -D cypress" }} />
+
+接下来，创建 `cypress.config.ts` 文件，并添加以下内容：
+
+```ts
+import { defineConfig } from 'cypress'
+
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on, config) {},
+  },
+})
+```
+
+## 编写测试用例
+
+现在，使用 Cypress 来编写一个 E2E 用例，首先创建两张 Modern.js 的页面。
+
+```tsx title="routes/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>Home</h1>
+    <Link to="/about">About</Link>
+  </div>
+);
+
+export default Index;
+```
+
+```tsx title="routes/about/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>About</h1>
+    <Link to="/">Home</Link>
+  </div>
+);
+
+export default Index;
+```
+
+接下来，创建测试用例文件：
+
+```ts title="cypress/e2e/app.cy.ts"
+describe('Navigation', () => {
+  it('should navigate to the about page', () => {
+    // Start from the index page
+    cy.visit('http://localhost:8080/')
+
+    // Find a link with an href attribute containing "about" and click it
+    cy.get('a[href*="about"]').click()
+
+    // The new url should include "/about"
+    cy.url().should('include', '/about')
+
+    // The new page should contain an h1 with "About"
+    cy.get('h1').contains('About')
+  })
+})
+```
+
+测试文件可能会缺少 API 的类型，你可以参考 [Cypress - Typescript](https://docs.cypress.io/guides/tooling/typescript-support#Configure-tsconfigjson) 文档解决。
+
+你可以将命令添加到 `package.json` 中：
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "cypress open"
+  }
+}
+```
+
+## 运行测试用例
+
+执行上述 `test` 命令，运行测试用例：
+
+```bash
+DevTools listening on ws://127.0.0.1:55203/devtools/browser/xxxxx
+```
+
+Cypress 会打开一个无头浏览器，按照提示你可以找到对应的测试文件，并自动运行 E2E 测试：
+
+![cypress](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/cypress.jpg)

package/docs/zh/guides/basic-features/testing/jest.mdx

@@ -0,0 +1,148 @@
+# Jest
+
+Jest 是一个 JavaScript 测试框架，它主要和 React Testing Library 一起用于单元测试和 Snapshot 测试。
+
+在 Modern.js 中使用 Jest 需要先安装依赖，可以执行以下命令：
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command={{
+  npm: "npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom",
+  yarn: "yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom",
+  pnpm: "pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom"
+}} />
+
+随后，你可以运行以下命令，这将自动在项目中初始化 Jest，并生成一个基础的 `jest.config.ts` 配置：
+
+<PackageManagerTabs command={{
+  npm: "npm init jest@latest",
+  yarn: "yarn create jest@latest",
+  pnpm: "pnpm create jest@latest"
+}} />
+
+## 配置文件
+
+:::note
+本章节会使用 `.ts` 文件来完成 Jest 测试。
+:::
+
+相比于其他的测试框架，Jest 在构建层面需要更多的配置，例如处理 JSX 和 ESM 语法，因此首先需要安装一些额外的依赖：
+
+<PackageManagerTabs command={{
+  npm: "npm install -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript",
+  yarn: "yarn add -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript",
+  pnpm: "pnpm install -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript"
+}} />
+
+### 配置 Jest
+
+你需要进一步配置 `jest.config.ts` 文件，以便让 Jest 能够正确地编译和运行测试用例。下面是一个最基本的配置：
+
+```ts title="jest.config.ts"
+import type { Config } from 'jest';
+
+const config: Config = {
+  coverageProvider: 'babel',
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
+  testEnvironment: 'jsdom',
+  transform: {
+    '^.+\\.(js|jsx|ts|tsx)$': 'babel-jest',
+  },
+  transformIgnorePatterns: [],
+};
+
+export default config;
+```
+
+配置中，将 `transformIgnorePatterns` 设置为了空数组，意味着所有的文件都会经过编译，如果你希望提升测试运行的速度，可以按需配置。
+
+`setupFilesAfterEnv` 会在启动时执行，在 `jest.setup.ts` 中，可以引入 `@testing-library/jest-dom`。它包含了一组便捷的自定义匹配器，例如 `.toBeInTheDocument()`，使编写测试变得更容易：
+
+```ts title="jest.setup.ts"
+import '@testing-library/jest-dom';
+```
+
+### 配置 Babel
+
+你需要配置 Babel 让 Jest 能够自动编译 JSX 等语法，下面是一个基本的配置：
+
+```js title="babel.config.js"
+module.exports = {
+  presets: [
+    ['@babel/preset-env', { targets: { node: 'current' } }],
+    ['@babel/preset-react', { runtime: 'automatic' }],
+    '@babel/preset-typescript',
+  ],
+};
+```
+
+## 编写测试用例
+
+现在，你可以开始编写测试用例了，首先在 `package.json` 中添加一个 `test` 命令：
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "jest"
+  }
+}
+```
+
+创建一个简单的页面用于测试：
+
+```tsx title="routes/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>Home</h1>
+    <Link to="/about">About</Link>
+  </div>
+);
+
+export default Index;
+```
+
+添加测试用例，检测页面中是否有预期的文本：
+
+```tsx title="__tests__/page.test.tsx"
+import '@testing-library/jest-dom';
+import { render, screen } from '@testing-library/react';
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
+import Page from '../routes/page';
+
+describe('Page', () => {
+  it('renders a heading', () => {
+    render(
+      <Router>
+        <Page />
+      </Router>,
+    );
+
+    const heading = screen.getByRole('heading', { level: 1 });
+
+    expect(heading).toBeInTheDocument();
+  });
+});
+```
+
+上述用例中，我们从 `@modern-js/runtime/router` 引入了 `<Router>` 组件，这是因为 React Router 在渲染部分路由相关组件时，必须要有对应的上下文。
+
+:::note
+直接在 Modern.js 应用中运行时，`<Router>` 组件会自动注入。
+:::
+
+## 运行测试用例
+
+执行上述 `test` 命令，运行测试用例：
+
+```bash
+ PASS  src/__tests__/page.test.tsx
+  Page
+    ✓ renders a heading (31 ms)
+
+Test Suites: 1 passed, 1 total
+Tests:       1 passed, 1 total
+Snapshots:   0 total
+Time:        0.959 s, estimated 1 s
+```