@modern-js/main-doc 2.25.2 → 2.26.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @modern-js/main-doc
 
+## 2.26.0
+
+### Patch Changes
+
+- @modern-js/builder-doc@2.26.0
+
 ## 2.25.2
 
 ### Patch Changes

package/docs/en/components/prerequisites.mdx

@@ -9,7 +9,7 @@ import NodeVersion from '@modern-js/builder-doc/docs/en/shared/nodeVersion.md';
 It is recommended to use [pnpm](https://pnpm.io/installation) to manage dependencies:
 
 ```bash
-npm install -g pnpm@7
+npm install -g pnpm@8
 ```
 
 :::note

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

@@ -32,14 +32,15 @@ When the value type is `Object`, the following properties can be configured:
 ```ts title="modern.config.ts"
 export default defineConfig({
   server: {
-    forceCSR: true,
-    mode: 'stream',
-    inlineScript: false,
+    ssr: {
+      forceCSR: true,
+      mode: 'stream',
+      inlineScript: false,
+    },
   },
 });
 ```
 
-
 ### Active Fallback
 
 In a production environment, there are scenarios where it is necessary to actively fallback an SSR project to CSR. Examples include
@@ -50,7 +51,7 @@ In a production environment, there are scenarios where it is necessary to active
 
 3. When the SSR server is under heavy load, it may be necessary to fallback some traffic directly to the CSR to avoid service downtime.
 
-By configuring `ssr.forCSR` to `true` in the project, you can control this behavior through query strings or request headers.
+By configuring `server.ssr.forceCSR` to `true` in the project, you can control this behavior through query strings or request headers.
 
 For example, in a custom Web Server middleware, you can actively fallback when traffic exceeds a certain threshold:
 

package/docs/en/configure/app/tools/swc.mdx

@@ -15,6 +15,8 @@ import SWC from '@modern-js/builder-doc/docs/en/shared/swc.md';
 
 :::tip
 When using Rspack as the bundler, SWC will be used for transpiling and compression by default, so you don't need to install or configure the SWC plugin.
+
+If you have configured the current SWC plugin when using Rspack, it will not have any effect.
 :::
 
 ## Install

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

@@ -13,7 +13,7 @@ import Prerequisites from "@site-docs-en/components/prerequisites"
 
 ## Installation
 
-Modern.js provides the `@modern-js/create` tool to create projects. Do not install it globally, use `npx` to run it.
+Modern.js provides the `@modern-js/create` tool to create projects. It does not require global installation and can be run on-demand using `npx`.
 
 You can create a project in an existing empty directory:
 
@@ -47,21 +47,41 @@ In a Modern.js project created using `@modern-js/create`, a `modern.config.ts` f
 You can modify the configuration through this file to override the default behavior of Modern.js. For example, to enable SSR, add the following configuration:
 
 ```ts
-import { defineConfig } from '@modern-js/app-tools';
+import { appTools, defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
   runtime: {
     router: true,
-    state: true,
   },
   server: {
     ssr: true,
   },
+  plugins: [appTools()],
 });
 ```
 
 After running `pnpm run dev` again, you can find that the project has completed page rendering on the server in the browser's Network menu.
 
+## Core npm Package
+
+In a newly created project, the `@modern-js/app-tools` npm package is installed by default. It is the core package of the Modern.js framework and provides the following capabilities:
+
+- It offers commonly used CLI commands such as `modern dev`, `modern build`, and more.
+- It integrates Modern.js Core, providing capabilities for configuration parsing, plugin loading, and more.
+- It integrates Modern.js Builder, providing build capabilities.
+- It integrates Modern.js Server, providing capabilities for development and production servers.
+- It integrates some commonly used plugins, such as `plugin-lint`, `plugin-data-loader`, and more.
+
+`@modern-js/app-tools` is implemented based on the plugin system of Modern.js. Essentially, it is a plugin. Therefore, you need to register `appTools` in the `plugins` field of the configuration file:
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  plugins: [appTools()],
+});
+```
+
 ## Build the project
 
 To build the production artifacts of the project, run `pnpm run build` in the project:

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

@@ -299,10 +299,21 @@ export const myPlugin = (): CliPlugin => ({
 
 ### `beforeCreateCompiler`
 
-- Function: Provides access to the Webpack configuration used to create the Webpack Compiler within middleware functions.
-- Execution Stage: Executed before creating the Webpack Compiler.
-- Hook Model: AsyncWorkflow.
-- Type: `AsyncWorkflow<{ webpackConfigs: Configuration[];}, unknown>`.
+- Function: A callback function triggered before creating the underlying Compiler instance, and you can get the final configuration array of the underlying bundler through the `bundlerConfigs` parameter:
+  - If the current bundler is webpack, you will get the webpack Compiler object.
+  - If the current bundler is Rspack, you will get the Rspack Compiler object.
+  - The configuration array may contain one or multiple configurations, depending on whether you have enabled features such as SSR.
+- Execution Stage: Executed before creating the Compiler instance when running the `dev` or `build` command.
+- Hook Model: `AsyncWorkflow`.
+- Type:
+
+```ts
+type BeforeCreateCompiler = AsyncWorkflow<
+  { bundlerConfigs: Configuration[] },
+  unknown
+>;
+```
+
 - Usage Example:
 
 ```ts
@@ -311,8 +322,9 @@ import type { CliPlugin } from '@modern-js/core';
 export const myPlugin = (): CliPlugin => ({
   setup(api) {
     return {
-      beforeCreateCompiler: ({ webpackConfigs }) => {
-        // do something
+      beforeCreateCompiler: ({ bundlerConfigs }) => {
+        console.log('Before create compiler.');
+        console.log(bundlerConfigs);
       },
     };
   },
@@ -321,10 +333,20 @@ export const myPlugin = (): CliPlugin => ({
 
 ### `afterCreateCompiler`
 
-- Function: Provides access to the created Webpack Compiler within middleware functions.
-- Execution Stage: Executed after creating the Webpack Compiler.
-- Hook Model: AsyncWorkflow.
-- Type: `AsyncWorkflow<{ compiler: Compiler | MultiCompiler | undefined; }, unknown>`.
+- Function: A callback function triggered after creating a Compiler instance and before executing the build. You can access the Compiler instance object through the `compiler` parameter:
+  - If the current bundler is webpack, you will get the webpack Compiler object.
+  - If the current bundler is Rspack, you will get the Rspack Compiler object.
+- Execution Stage: Executed after creating the Compiler object.
+- Hook Model: `AsyncWorkflow`.
+- Type:
+
+```ts
+type AfterCreateCompiler = AsyncWorkflow<
+  { compiler: Compiler | MultiCompiler | undefined },
+  unknown
+>;
+```
+
 - Usage Example:
 
 ```ts
@@ -334,7 +356,8 @@ export const myPlugin = (): CliPlugin => ({
   setup(api) {
     return {
       afterCreateCompiler: ({ compiler }) => {
-        // do something
+        console.log('After create compiler.');
+        console.log(compiler);
       },
     };
   },
@@ -368,10 +391,20 @@ export const myPlugin = (): CliPlugin => ({
 
 ### `beforeBuild`
 
-- Function: Tasks to be executed before the main process of the `build` command, provides access to the Webpack configuration used for building.
-- Execution Stage: Executed before starting the project build when running the `build` command.
-- Hook Model: AsyncWorkflow.
-- Type: `AsyncWorkflow<{ webpackConfigs: Configuration[]; }>`.
+- Function: A callback function triggered before executing production environment builds. You can access the final configuration array of the underlying bundler through the `bundlerConfigs` parameter.
+  - If the current bundler is webpack, you will get the webpack Compiler object.
+  - If the current bundler is Rspack, you will get the Rspack Compiler object.
+  - The configuration array may contain one or multiple configurations, depending on whether you have enabled features such as SSR.
+- Execution Stage: Executed after running the `build` command and before the actual build process begins.
+- Hook Model: `AsyncWorkflow`.
+- Type:
+
+```ts
+type BeforeBuild = AsyncWorkflow<{
+  bundlerConfigs: WebpackConfig[] | RspackConfig[];
+}>;
+```
+
 - Usage Example:
 
 ```ts
@@ -380,8 +413,9 @@ import type { CliPlugin } from '@modern-js/core';
 export const myPlugin = (): CliPlugin => ({
   setup(api) {
     return {
-      beforeBuild: () => {
-        // do something
+      beforeBuild: ({ bundlerConfigs }) => {
+        console.log('Before build.');
+        console.log(bundlerConfigs);
       },
     };
   },
@@ -390,10 +424,19 @@ export const myPlugin = (): CliPlugin => ({
 
 ### `afterBuild`
 
-- Function: Tasks to be executed after the main process of the `build` command.
-- Execution Stage: Executed after the project build is completed when running the `build` command.
-- Hook Model: AsyncWorkflow.
-- Type: `AsyncWorkflow<void, unknown>`.
+- Function: A callback function triggered after running the production build. You can access the build result information through the `stats` parameter.
+  - If the current bundler is webpack, you will get webpack Stats.
+  - If the current bundler is Rspack, you will get Rspack Stats.
+- Execution Stage: It is executed after running the `build` command and completing the build.
+- Hook Model: `AsyncWorkflow`.
+- Type:
+
+```ts
+type AfterBuild = AsyncWorkflow<{
+  stats?: Stats | MultiStats;
+}>;
+```
+
 - Usage Example:
 
 ```ts
@@ -402,8 +445,9 @@ import type { CliPlugin } from '@modern-js/core';
 export const myPlugin = (): CliPlugin => ({
   setup(api) {
     return {
-      afterBuild: () => {
-        // do something
+      afterBuild: ({ stats }) => {
+        console.log('After build.');
+        console.log(stats);
       },
     };
   },

package/docs/en/guides/topic-detail/generator/plugin/api/onForged.md

@@ -215,7 +215,7 @@ Parameter types:
 updateInfo: Record<string, any>
 ```
 
-- `updateInfo`: Update content information. `updateModernConfig` is a package based on `updateJSONFile`, which will automatically update under the `edenxConfig` field. Only the configuration fields under `modernConfig` need to be filled in `updateInfo`.
+- `updateInfo`: Update content information. `updateModernConfig` is a package based on `updateJSONFile`, which will automatically update under the `modernConfig` field. Only the configuration fields under `modernConfig` need to be filled in `updateInfo`.
 
 For example, enable SSR:
 

package/docs/zh/components/prerequisites.mdx

@@ -9,7 +9,7 @@ import NodeVersion from '@modern-js/builder-doc/docs/zh/shared/nodeVersion.md';
 推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
 
 ```bash
-npm install -g pnpm@7
+npm install -g pnpm@8
 ```
 
 :::note

package/docs/zh/configure/app/deploy/microFrontend.mdx

@@ -52,4 +52,4 @@ export default defineConfig({
 
 - **默认值：** `false`
 
-是否 `external` 基础库，当设置为 `true` 时，当前子应用将会 `external`：`react`、`react-dom`，`EdenX` 主应用会自动 `setExternal` 这两个基础库，如果其他类型的框架请通过 `Garfish.setExternal` 增加 `react`、`react-dom` 依赖
+是否 `external` 基础库，当设置为 `true` 时，当前子应用将会 `external`：`react`、`react-dom`，`Modern.js` 主应用会自动 `setExternal` 这两个基础库，如果其他类型的框架请通过 `Garfish.setExternal` 增加 `react`、`react-dom` 依赖

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

@@ -29,13 +29,14 @@ export default defineConfig({
 - `forceCSR`：`boolean = false`，默认关闭强制 CSR 渲染。配置为 `true` 后，在页面访问时添加 `?csr=true` 或添加请求头 `x-modern-ssr-fallback` 即可强制 CSR。
 - `inlineScript`：`boolean = true`，默认情况下，SSR 的数据会以内联脚本的方式注入到 HTML 中，并且直接赋值给全局变量。配置为 `false` 后，会下发 JSON，而不是赋值给全局变量。
 
-
 ```ts title="modern.config.ts"
 export default defineConfig({
   server: {
-    forceCSR: true,
-    mode: 'stream',
-    inlineScript: false,
+    ssr: {
+      forceCSR: true,
+      mode: 'stream',
+      inlineScript: false,
+    },
   },
 });
 ```
@@ -50,7 +51,7 @@ export default defineConfig({
 
 3. SSR 服务压力过大，需要部分流量直接降级为 CSR，避免服务宕机。
 
-在项目中配置 `ssr.forCSR` 为 `true` 后，我们可以通过请求的查询字符串，或是请求头来控制这一行为。
+在项目中配置 `server.ssr.forceCSR` 为 `true` 后，我们可以通过请求的查询字符串，或是请求头来控制这一行为。
 
 例如在自定义 Web Server 的中间件中，检测到流量大于某一阈值时，主动降级：
 

package/docs/zh/configure/app/tools/swc.mdx

@@ -15,6 +15,8 @@ import SWC from '@modern-js/builder-doc/docs/zh/shared/swc.md';
 
 :::tip
 在使用 Rspack 作为打包工具时，默认会使用 SWC 进行转译和压缩，因此你不需要再安装和配置 SWC 插件。
+
+如果你使用 Rspack 时配置了当前的 SWC 插件，它将不会产生任何效果。
 :::
 
 ## 安装

package/docs/zh/guides/advanced-features/using-storybook.mdx

@@ -14,7 +14,7 @@ sidebar_position: 20
 
 ## 开启 Storybook 调试
 
-EdenX 默认集成了 Storybook 的调试能力。
+Modern.js 默认集成了 Storybook 的调试能力。
 
 当我们想要对组件进行调试的时候，可以通过 `pnpm run new` 启用 Storybook 调试功能。
 

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

@@ -2,19 +2,20 @@
 title: 快速上手
 sidebar_position: 2
 ---
+
 # 快速上手
 
 ## 环境准备
 
-import Prerequisites from "@site-docs/components/prerequisites"
+import Prerequisites from '@site-docs/components/prerequisites';
 
 <Prerequisites />
 
 ## 安装
 
-Modern.js 提供了 `@modern-js/create` 工具来创建项目，不要全局安装，使用 `npx` 按需运行。
+Modern.js 提供了 `@modern-js/create` 工具来创建项目，不需要全局安装，直接使用 `npx` 按需运行即可。
 
-可以在已有的空目录来创建项目：
+你可以在已有的空目录来创建项目：
 
 ```bash
 mkdir myapp && cd myapp
@@ -29,13 +30,13 @@ npx @modern-js/create@latest myapp
 
 ## 初始化项目
 
-import InitApp from "@site-docs/components/init-app"
+import InitApp from '@site-docs/components/init-app';
 
 <InitApp />
 
 ## 启动项目
 
-import DebugApp from "@site-docs/components/debug-app"
+import DebugApp from '@site-docs/components/debug-app';
 
 <DebugApp />
 
@@ -43,7 +44,7 @@ import DebugApp from "@site-docs/components/debug-app"
 
 通过 `@modern-js/create` 创建的 Modern.js 项目中，会默认生成 `modern.config.ts` 文件。
 
-可以通过该配置文件修改配置，覆盖 Modern.js 的默认行为。例如添加如下配置，开启 SSR：
+你可以通过该配置文件修改配置，覆盖 Modern.js 的默认行为。例如添加如下配置，开启 SSR：
 
 ```ts title="modern.config.ts"
 import { appTools, defineConfig } from '@modern-js/app-tools';
@@ -61,6 +62,26 @@ export default defineConfig({
 
 重新执行 `pnpm run dev`，在浏览器 Network 菜单中，可以发现项目已经在服务端完成了页面渲染。
 
+## 核心 npm 包
+
+在新创建的工程中，默认会安装 `@modern-js/app-tools` npm 包，它是 Modern.js 框架的核心包，主要提供以下能力：
+
+- 提供 `modern dev`, `modern build` 等常用的 CLI 命令。
+- 集成 Modern.js Core，提供配置解析、插件加载等能力。
+- 集成 Modern.js Builder，提供构建能力。
+- 集成 Modern.js Server，提供开发和生产服务器相关能力。
+- 集成一些最为常用的插件，比如 `plugin-lint`、`plugin-data-loader` 等。
+
+`@modern-js/app-tools` 是基于 Modern.js 的插件体系实现的，本质上是一个插件，因此你需要在配置文件的 `plugins` 字段中注册 `appTools`：
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  plugins: [appTools()],
+});
+```
+
 ## 构建项目
 
 在项目中执行 `pnpm run build` 即可构建项目生产环境产物：
@@ -125,6 +146,6 @@ info    App running at:
 
 ## 部署
 
-import Deploy from "@site-docs/components/deploy"
+import Deploy from '@site-docs/components/deploy';
 
 <Deploy />

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

@@ -299,10 +299,21 @@ export const myPlugin = (): CliPlugin => ({
 
 ### `beforeCreateCompiler`
 
-- 功能：在中间件函数中可以拿到创建 Webpack Compiler 的 Webpack 配置
-- 执行阶段：创建 Webpack Compiler 之前执行
-- Hook 模型：AsyncWorkflow
-- 类型：`AsyncWorkflow<{ webpackConfigs: Configuration[];}, unknown>`
+- 功能：在创建底层 Compiler 实例前触发的回调函数，并且你可以通过 `bundlerConfigs` 参数获取到底层打包工具的最终配置数组：
+  - 如果当前打包工具为 webpack，则获取到的是 webpack 配置数组。
+  - 如果当前打包工具为 Rspack，则获取到的是 Rspack 配置数组。
+  - 配置数组中可能包含一份或多份配置，这取决于你是否开启了 SSR 等功能。
+- 执行阶段：在执行 dev 或 build 命令时，创建 Compiler 实例之前执行
+- Hook 模型：`AsyncWorkflow`
+- 类型：
+
+```ts
+type BeforeCreateCompiler = AsyncWorkflow<
+  { bundlerConfigs: Configuration[] },
+  unknown
+>;
+```
+
 - 使用示例：
 
 ```ts
@@ -311,8 +322,9 @@ import type { CliPlugin } from '@modern-js/core';
 export const myPlugin = (): CliPlugin => ({
   setup(api) {
     return {
-      beforeCreateCompiler: ({ webpackConfigs }) => {
-        // do something
+      beforeCreateCompiler: ({ bundlerConfigs }) => {
+        console.log('Before create compiler.');
+        console.log(bundlerConfigs);
       },
     };
   },
@@ -321,10 +333,20 @@ export const myPlugin = (): CliPlugin => ({
 
 ### `afterCreateCompiler`
 
-- 功能：在中间件函数中可以拿到创建的 Webpack Compiler
-- 执行阶段：创建 Webpack Compiler 之后执行
-- Hook 模型：AsyncWorkflow
-- 类型：`AsyncWorkflow<{ compiler: Compiler | MultiCompiler | undefined; }, unknown>`
+- 功能：在创建 Compiler 实例后、执行构建前触发的回调函数，并且你可以通过 `compiler` 参数获取到 Compiler 实例对象：
+  - 如果当前打包工具为 webpack，则获取到的是 webpack Compiler 对象。
+  - 如果当前打包工具为 Rspack，则获取到的是 Rspack Compiler 对象。
+- 执行阶段：创建 Compiler 对象之后执行
+- Hook 模型：`AsyncWorkflow`
+- 类型：
+
+```ts
+type AfterCreateCompiler = AsyncWorkflow<
+  { compiler: Compiler | MultiCompiler | undefined },
+  unknown
+>;
+```
+
 - 使用示例：
 
 ```ts
@@ -334,7 +356,8 @@ export const myPlugin = (): CliPlugin => ({
   setup(api) {
     return {
       afterCreateCompiler: ({ compiler }) => {
-        // do something
+        console.log('After create compiler.');
+        console.log(compiler);
       },
     };
   },
@@ -368,10 +391,20 @@ export const myPlugin = (): CliPlugin => ({
 
 ### `beforeBuild`
 
-- 功能：运行 build 主流程的之前的任务，可以拿到构建的 Webpack 配置
-- 执行阶段：`build` 命令运行时，项目构建启动前执行
-- Hook 模型：AsyncWorkflow
-- 类型：`AsyncWorkflow<{ webpackConfigs: Configuration[]; }>`
+- 功能：在执行生产环境构建前触发的回调函数，你可以通过 `bundlerConfigs` 参数获取到底层打包工具的最终配置数组。
+  - 如果当前打包工具为 webpack，则获取到的是 webpack 配置数组。
+  - 如果当前打包工具为 Rspack，则获取到的是 Rspack 配置数组。
+  - 配置数组中可能包含一份或多份配置，这取决于你是否开启了 SSR 等功能。
+- 执行阶段：运行 `build` 命令后，在开始构建前执行
+- Hook 模型：`AsyncWorkflow`
+- 类型：
+
+```ts
+type BeforeBuild = AsyncWorkflow<{
+  bundlerConfigs: WebpackConfig[] | RspackConfig[];
+}>;
+```
+
 - 使用示例：
 
 ```ts
@@ -380,8 +413,9 @@ import type { CliPlugin } from '@modern-js/core';
 export const myPlugin = (): CliPlugin => ({
   setup(api) {
     return {
-      beforeBuild: () => {
-        // do something
+      beforeBuild: ({ bundlerConfigs }) => {
+        console.log('Before build.');
+        console.log(bundlerConfigs);
       },
     };
   },
@@ -390,10 +424,19 @@ export const myPlugin = (): CliPlugin => ({
 
 ### `afterBuild`
 
-- 功能：运行 build 主流程的之后的任务
-- 执行阶段：`build` 命令运行时，项目构建完成之后执行
-- Hook 模型：AsyncWorkflow
-- 类型：`AsyncWorkflow<void, unknown>`
+- 功能：在执行生产环境构建后触发的回调函数，你可以通过 `stats` 参数获取到构建结果信息。
+  - 如果当前打包工具为 webpack，则获取到的是 webpack Stats。
+  - 如果当前打包工具为 Rspack，则获取到的是 Rspack Stats。
+- 执行阶段：运行 `build` 命令运行后，在项目构建完成之后执行
+- Hook 模型：`AsyncWorkflow`
+- 类型：
+
+```ts
+type AfterBuild = AsyncWorkflow<{
+  stats?: Stats | MultiStats;
+}>;
+```
+
 - 使用示例：
 
 ```ts
@@ -402,8 +445,9 @@ import type { CliPlugin } from '@modern-js/core';
 export const myPlugin = (): CliPlugin => ({
   setup(api) {
     return {
-      afterBuild: () => {
-        // do something
+      afterBuild: ({ stats }) => {
+        console.log('After build.');
+        console.log(stats);
       },
     };
   },

package/package.json

@@ -15,14 +15,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.25.2",
+  "version": "2.26.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.25.2"
+    "@modern-js/builder-doc": "^2.26.0"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -34,9 +34,9 @@
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.25.2",
-    "@modern-js/doc-plugin-auto-sidebar": "2.25.2",
-    "@modern-js/doc-tools": "2.25.2"
+    "@modern-js/builder-doc": "2.26.0",
+    "@modern-js/doc-tools": "2.26.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.26.0"
   },
   "scripts": {
     "dev": "modern dev",