@modern-js/main-doc 2.42.1 → 2.43.0

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

@@ -0,0 +1,155 @@
+---
+sidebar_position: 11
+---
+
+# Import SVG Assets
+
+Modern.js supports import SVG assets and transform SVG into React components or URLs.
+
+:::tip What is SVG
+SVG stands for Scalable Vector Graphics. It is a type of image format that uses vector graphics to represent images. Vector graphics are different from raster graphics, which are made up of pixels. Instead, vector graphics use geometric shapes, lines, and curves to represent images. Because vector graphics are not made up of pixels, they can be scaled to any size without losing resolution or quality.
+:::
+
+## Import SVG in JS file
+
+When import an SVG in a JS file, if you import `ReactComponent`, Modern.js will call [SVGR](https://react-svgr.com/) to convert the SVG into a React component.
+
+```tsx title="src/component/Logo.tsx"
+import { ReactComponent as Logo } from './static/logo.svg';
+
+export default () => <Logo />;
+```
+
+If you use the default import, then the SVG will be treated as a normal static asset and you will get a URL:
+
+```tsx title="src/component/Logo.tsx"
+import logoURL from './static/logo.svg';
+
+console.log(logoURL); // => "/static/logo.6c12aba3.png"
+```
+
+## Modify the Default Export
+
+You can modify the default export of SVG files through the [output.svgDefaultExport](/configure/app/output/svg-default-export) config. For example, set the default export as a React component:
+
+```ts
+export default {
+  output: {
+    svgDefaultExport: 'component',
+  },
+};
+```
+
+Then import the SVG, you'll get a React component instead of a URL:
+
+```tsx title="src/component/Logo.tsx"
+import Logo from './static/logo.svg';
+
+export default () => <Logo />;
+```
+
+## Import SVG in CSS file
+
+When import an SVG in a CSS file, the SVG is treated as a normal static asset and you will get a URL:
+
+```css
+.logo {
+  background-image: url('../static/logo.svg');
+}
+```
+
+## Assets Processing
+
+When SVG is imported not as a React component but as a normal static asset, it is processed exactly the same as other static assets, and it is also affected by rules such as assets inlining and URL prefixing.
+
+Please read the [Import Static Assets](/guides/basic-features/static-assets) section to understand the processing rules for static assets.
+
+## Disable SVGR Processing
+
+By default, when an SVG resource is referenced in a JS file, Modern.js will call SVGR to convert the SVG into a React component. If you are sure that all SVG resources in your project are not being used as React components, you can turn off this conversion by setting [disableSvgr](/configure/app/output/disable-svgr) to true to improve build performance.
+
+```js
+export default {
+  output: {
+    disableSvgr: true,
+  },
+};
+```
+
+## Add type declaration
+
+When you reference an SVG asset in TypeScript code, TypeScript may prompt that the module is missing a type definition:
+
+```
+TS2307: Cannot find module './logo.svg' or its corresponding type declarations.
+```
+
+To fix this, you need to add a type declaration file for the SVG asset, please create a `src/global.d.ts` file, and add the following type declaration:
+
+```ts
+declare module '*.svg' {
+  export const ReactComponent: React.FunctionComponent<
+    React.SVGProps<SVGSVGElement>
+  >;
+
+  const content: string;
+  export default content;
+}
+```
+
+If you set `svgDefaultExport` to `'component'`, then change the type declaration to:
+
+```ts
+declare module '*.svg' {
+  export const ReactComponent: React.FunctionComponent<
+    React.SVGProps<SVGSVGElement>
+  >;
+
+  export default ReactComponent;
+}
+```
+
+After adding the type declaration, if the type error still exists, you can try to restart the current IDE, or adjust the directory where `global.d.ts` is located, making sure the TypeScript can correctly identify the type definition.
+
+## Modify the SVGR configuration
+
+When SVGR is enabled, its default configuration is as follows:
+
+```js
+{
+  svgo: true,
+  svgoConfig: {
+    plugins: [
+      {
+        name: 'preset-default',
+        params: {
+          overrides: {
+            removeViewBox: false,
+          },
+        },
+      },
+      'prefixIds',
+    ],
+  },
+}
+```
+
+If you need to modify the SVGR configuration, you can do the following:
+
+```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/en/guides/basic-features/wasm-assets.mdx

@@ -0,0 +1,66 @@
+---
+sidebar_position: 13
+---
+
+# Import Wasm Assets
+
+Modern.js supports import WebAssembly assets in code.
+
+:::tip What is WebAssembly
+WebAssembly (Wasm) is a portable, high-performance binary format designed to execute CPU-intensive computing tasks in modern web browsers, bringing performance and reliability similar to native compiled code to the web platform.
+:::
+
+## Import
+
+You can import a WebAssembly module directly in a JavaScript file:
+
+```js title="index.js"
+import { add } from './add.wasm';
+
+console.log(add); // [native code]
+console.log(add(1, 2)); // 3
+```
+
+WebAssembly modules can also be imported via dynamic import:
+
+```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
+});
+```
+
+You can also get the path of a WebAssembly module using the `new URL` syntax:
+
+```js title="index.js"
+const wasmURL = new URL('./add.wasm', import.meta.url);
+
+console.log(wasmURL).pathname; // "/static/wasm/[hash].module.wasm"
+```
+
+## Output Directory
+
+When a `.wasm` asset is imported, it will be output by Modern.js to the `dist/static/wasm` directory by default.
+
+You can change the output directory of `.wasm` files via [output.distPath](/configure/app/output/dist-path) config.
+
+```ts
+export default {
+  output: {
+    distPath: {
+      wasm: 'resource/wasm',
+    },
+  },
+};
+```
+
+## Add Type Declaration
+
+When you import a Wasm file in TypeScript code, you usually need to add the corresponding type declaration.
+
+For example, the `add.wasm` file exports an `add()` method, then you can create an `add.wasm.d.ts` file in the same directory and add the corresponding type declaration:
+
+```ts title="add.wasm.d.ts"
+export const add = (num1: number, num2: number) => number;
+```

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

@@ -116,7 +116,7 @@ dist
     └── js
 ```
 
-> If you need to customize the directory of the build artifacts, please refer to [Output files](https://modernjs.dev/builder/guide/basic/output-files.html).
+> If you need to customize the directory of the build artifacts, please refer to [Output files](/guides/basic-features/output-files).
 
 ## Verify
 

package/docs/en/guides/get-started/tech-stack.mdx

@@ -97,7 +97,7 @@ Modern.js supports three CSS preprocessors: [Sass](https://sass-lang.com/), [Les
 
 Modern.js provides out-of-the-box support for [CSS Modules](https://github.com/css-modules/css-modules), which is implemented internally based on [css-loader](https://www.npmjs.com/package/css-loader).
 
-Please refer to ["Use CSS Modules"](https://modernjs.dev/builder/en/guide/basic/css-modules.html) for usage instructions.
+Please refer to ["Use CSS Modules"](/guides/basic-features/css-modules) for usage instructions.
 
 ---
 

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

@@ -6,22 +6,69 @@ sidebar_position: 1
 
 ## Modern.js Plugin System
 
-Modern.js is a system used for extending the functionality of a project at different stages such as running, requesting, and rendering. It mainly consists of three parts: the Hook model, the Manager, and the Context Sharing mechanism.
-
-The Hook model is used to determine the execution method of the current Hook, and functions with different Hook models have different execution logics. The Manager is used to control the execution and scheduling of Hooks. The Context Sharing mechanism is used to pass information between different Hooks.
-
-Currently, Modern.js provides several different Hook models:
-
-- Pipeline
-  - Sync
-  - Async
-- Waterfall
-  - Sync
-  - Async
-- Workflow
-  - Sync
-  - Async
-  - Parallel(Async)
+Modern.js offers a comprehensive plugin system with a complete lifecycle. Plugins can be used to extend different stages of project operation, request handling, rendering, and more.
+
+## Usage
+
+Plugins must be explicitly registered in the configuration file to be effective. When you need to add plugins to Modern.js, you can configure them in the `[plugin](/configure/app/plugins.html)` field:
+
+```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
+Note that this configuration only supports adding Modern.js plugins and does not support adding Webpack plugins.
+:::
+
+## Official Plugins
+
+Modern.js offers a range of official plugins, which are integrated with the Modern.js generator. All the functionalities of the official plugins can be enabled by executing the `new` command. For instance, to enable the BFF (Backend For Frontend) feature:
+
+```bash
+$ npx modern new
+? Please select the operation you want: Enable Features
+? Please select the feature name: (Use arrow keys)
+  Enable Tailwind CSS
+❯ Enable BFF
+  Enable SSG
+  Enable Micro Frontend
+  Enable Unit Test / Integration Test
+  Enable Visual Testing (Storybook)
+```
+
+After the selection is completed, the Modern.js generator will automatically install the corresponding plugins and third-party dependencies. Upon completion of the installation, you will see:
+
+```bash
+[INFO] Dependency automatic installation succeeded
+
+[INFO] install plugin dependencies success！add follow code to modern.config.ts :
+
+import { bffPlugin } from '@modern-js/plugin-bff';
+import { expressPlugin } from '@modern-js/plugin-express';
+
+export default defineConfig({
+  ...,
+  plugins: [..., bffPlugin(), expressPlugin()],
+});
+```
+
+At this point, you can add the plugin to the configuration file according to the output in the console.
+
+## Composition
+
+The Modern.js plugin system is mainly divided into three parts: Hook model, Manager, and Context Sharing Mechanism.
+
+- The Hook model is used to determine the execution logic of the current Hook.
+- The Manager controls the execution and scheduling of Hooks.
+- The Context Sharing Mechanism is used to pass information between different Hooks.
+
+Currently, Modern.js offers several different Hook models: **Pipeline, Waterfall, Workflow**.
 
 :::note
 Subsequent chapters will introduce the execution methods of each model in detail.

package/docs/zh/apis/app/runtime/web-server/middleware.mdx

@@ -91,7 +91,7 @@ type MiddlewareContext = {
 ```ts
 export const Middleware = () => async (ctx, next) => {
   const start = Date.now();
-  ctx.res.once('finish', () => {
+  ctx.source.res.once('finish', () => {
     console.log(Date.now() - start);
   });
 };
@@ -99,12 +99,12 @@ export const Middleware = () => async (ctx, next) => {
 
 ### 注入服务端工具 & 数据
 
-Modern.js 提供了 `res.locals` 属性用来存放当前请求的局部变量。
+Modern.js 提供了 `response.locals` 属性用来存放当前请求的局部变量。
 
 ```ts
 export const Middleware = () => async (ctx, next) => {
-  ctx.res.locals.id = 'Modern.js';
-  ctx.res.locals.rpc = createRpcInstance();
+  ctx.response.locals.id = 'Modern.js';
+  ctx.response.locals.rpc = createRpcInstance();
 };
 ```
 

package/docs/zh/configure/app/server/ssr.mdx

@@ -30,6 +30,7 @@ export default defineConfig({
 - `inlineScript`：`boolean = true`，默认情况下，SSR 的数据会以内联脚本的方式注入到 HTML 中，并且直接赋值给全局变量。配置为 `false` 后，会下发 JSON，而不是赋值给全局变量。
 - `disablePrerender`: `boolean = fasle`, 为了兼容旧数据请求方式 - `useLoader`, 默认情况下 Modern.js 会对组件进行一次预渲染即有两次渲染。
   开发者在保证项目中没有使用 useLoader Api 情况下, 可通过配置 `disablePrerender=true`来减少一次渲染。
+- `unsafeHeaders`: `string[] = []`, 为了安全考虑，Modern.js 不会往 SSR_DATA 添加过多的内容。开发者可以通过该配置，对需要注入的 headers 进行配置。
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -39,6 +40,7 @@ export default defineConfig({
       mode: 'stream',
       inlineScript: false,
       disablePrerender: true,
+      unsafeHeaders: ['User-Agent'],
     },
   },
 });

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 中一些常见的产物体积优化方式。
 
 ## 减少重复依赖
 
@@ -77,18 +77,19 @@ export default {
 ```
 
 :::tip
-请阅读 [浏览器兼容性](https://modernjs.dev/builder/guide/advanced/browser-compatibility.html) 章节来了解更多关于 polyfill 的用法。
+请阅读 [浏览器兼容性](/guides/advanced-features/compatibility) 章节来了解更多关于 polyfill 的用法。
 :::
 
 ## 使用图片压缩
 
-在一般的前端项目中，图片资源的体积往往是项目产物体积的大头，因此如果能尽可能精简图片的体积，那么将会对项目的打包产物体积起到明显的优化效果。你可以在 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/advanced-features/ssr/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "服务端渲染",
+  "position": 3,
+  "link": {
+    "type": "doc",
+    "id": "guides/advanced-features/ssr/index"
+  }
+}