@modern-js/main-doc 2.55.0 → 2.56.1

package/docs/en/configure/app/dev/live-reload.mdx

@@ -0,0 +1,27 @@
+---
+sidebar_label: liveReload
+---
+
+# dev.liveReload
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to reload the page when source files are changed.
+
+By default, Modern.js uses HMR as the preferred method to update modules. If HMR is disabled or cannot be used in certain scenarios, it will automatically fallback to liveReload.
+
+Please refer to [Hot Module Replacement](https://rsbuild.dev/guide/advanced/hmr) for more information.
+
+## Disabling liveReload
+
+If you need to disable liveReload, you can set both `dev.hmr` and `dev.liveReload` to `false`. Then, no Web Socket requests will be made to the dev server on the page, and the page will not automatically refresh when file change.
+
+```js
+export default {
+  dev: {
+    hmr: false,
+    liveReload: false,
+  },
+};
+```

package/docs/en/configure/app/dev/setup-middlewares.mdx

@@ -0,0 +1,69 @@
+---
+sidebar_label: setupMiddlewares
+---
+
+# dev.setupMiddlewares
+
+- **Type:**
+
+```ts
+type ServerAPIs = {
+  sockWrite: (
+    type: string,
+    data?: string | boolean | Record<string, any>,
+  ) => void;
+};
+
+type SetupMiddlewares = Array<
+  (
+    middlewares: {
+      unshift: (...handlers: RequestHandler[]) => void;
+      push: (...handlers: RequestHandler[]) => void;
+    },
+    server: ServerAPIs,
+  ) => void
+>;
+```
+
+- **Default:** `undefined`
+
+Provides the ability to execute a custom function and apply custom middlewares.
+
+The order among several different types of middleware is: `unshift` => internal middlewares => `push`.
+
+```js
+export default {
+  dev: {
+    setupMiddlewares: [
+      (middlewares, server) => {
+        middlewares.unshift((req, res, next) => {
+          next();
+        });
+
+        middlewares.push((req, res, next) => {
+          next();
+        });
+      },
+    ],
+  },
+};
+```
+
+It is possible to use some server api to meet special scenario requirements:
+
+- sockWrite. Allow send some message to HMR client, and then the HMR client will take different actions depending on the message type. If you send a "content changed" message, the page will reload.
+
+```js
+export default {
+  dev: {
+    setupMiddlewares: [
+      (middlewares, server) => {
+        // add custom watch & trigger page reload when change
+        watcher.on('change', (changed) => {
+          server.sockWrite('content-changed');
+        });
+      },
+    ],
+  },
+};
+```

package/docs/en/configure/app/dev/watch-files.mdx

@@ -0,0 +1,59 @@
+---
+sidebar_label: watchFiles
+---
+
+# dev.watchFiles
+
+- **Type:**
+
+```ts
+type WatchFiles = {
+  paths: string | string[];
+  // watch options for chokidar
+  options?: WatchOptions;
+};
+```
+
+- **Default:** `undefined`
+
+Watch files and directories for changes. When a file changes, the page will be reloaded.
+
+If both `dev.hmr` and `dev.liveReload` are set to false, `watchFiles` will be ignored.
+
+:::tip
+When files in WatchFiles change, reloading and recompilation of the configuration file will not be triggered.
+:::
+
+### Example
+
+You can configure a list of globs/directories/files to watch for file changes.
+
+```js
+export default {
+  dev: {
+    watchFiles: {
+      // watch a single file
+      paths: 'public/demo.txt',
+      // use a glob pattern
+      paths: 'src/**/*.txt',
+      // watch multiple file paths
+      paths: ['src/**/*.txt', 'public/**/*'],
+    },
+  },
+};
+```
+
+You can also specify [chokidar](https://github.com/paulmillr/chokidar#api) watcher options by passing an object with `paths` and `options` properties.
+
+```js
+export default {
+  dev: {
+    watchFiles: {
+      paths: 'src/**/*.txt',
+      options: {
+        usePolling: false,
+      },
+    },
+  },
+};
+```

package/docs/en/configure/app/dev/write-to-disk.mdx

@@ -0,0 +1,38 @@
+---
+sidebar_label: writeToDisk
+---
+
+# dev.writeToDisk
+
+- **Type:** `boolean | ((filename: string) => boolean)`
+- **Default:** `(file) => !file.includes('.hot-update.')`
+
+Used to control whether the build artifacts of the development environment are written to the disk.
+
+## Writing to Memory
+
+You can choose to save the build artifacts in the memory of the dev server, thereby reducing the overhead caused by file operations.
+
+Simply set the `dev.writeToDisk` option to `false`:
+
+```ts
+export default {
+  dev: {
+    writeToDisk: false,
+  },
+};
+```
+
+## Matching Specific Files
+
+You can also set `dev.writeToDisk` to a function to match only certain files. When the function returns `false`, the file will not be written; when it returns `true`, the file will be written to disk.
+
+For example, Modern.js by default write files to disk while excluding hot-update temporary files:
+
+```ts
+export default {
+  dev: {
+    writeToDisk: (file) => !file.includes('.hot-update.'),
+  },
+};
+```

package/docs/en/guides/basic-features/data/data-fetch.mdx

@@ -247,7 +247,7 @@ In a multi-entry (MPA) scenario, the value of `routeId` needs to include the nam
 
 If you want to get the data returned by the `loader` in `entry1/routes/layout.tsx`, the value of `routeId` is `entry1_layout`.
 
-### (WIP)Loading UI
+### Loading UI (Experimental)
 
 :::info
 This feature is currently experimental and the API may change in the future.

package/docs/en/guides/basic-features/routes.mdx

@@ -290,7 +290,7 @@ When accessing the route, you will get the following UI layout:
 </RootLayout>
 ```
 
-### (WIP)Loading
+### Loading (Experimental)
 
 In each directory under `routes/`, developers can create a `loading.tsx` file that exports a `<Loading>` component by default.
 

package/docs/zh/configure/app/dev/live-reload.mdx

@@ -0,0 +1,27 @@
+---
+sidebar_label: liveReload
+---
+
+# dev.liveReload
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否在源文件变更时自动刷新页面。
+
+默认情况下，Modern.js 会优先使用 HMR 来更新模块。当 HMR 功能被禁用，或者某些场景 HMR 无法生效时，会自动降级到 liveReload。
+
+请查看 [模块热更新](https://rsbuild.dev/zh/guide/advanced/hmr) 来了解更多内容。
+
+## 禁用 liveReload
+
+如果你需要禁用 liveReload，可以将 `dev.hmr` 和 `dev.liveReload` 同时设置为 `false`，此时页面上不会发起 Web Socket 请求到 dev server，也不会在文件变更时自动刷新页面。
+
+```js
+export default {
+  dev: {
+    hmr: false,
+    liveReload: false,
+  },
+};
+```

package/docs/zh/configure/app/dev/setup-middlewares.mdx

@@ -0,0 +1,69 @@
+---
+sidebar_label: setupMiddlewares
+---
+
+# dev.setupMiddlewares
+
+- **类型：**
+
+```ts
+type ServerAPIs = {
+  sockWrite: (
+    type: string,
+    data?: string | boolean | Record<string, any>,
+  ) => void;
+};
+
+type SetupMiddlewares = Array<
+  (
+    middlewares: {
+      unshift: (...handlers: RequestHandler[]) => void;
+      push: (...handlers: RequestHandler[]) => void;
+    },
+    server: ServerAPIs,
+  ) => void
+>;
+```
+
+- **默认值：** `undefined`
+
+提供执行自定义函数和应用自定义中间件的能力。
+
+中间件的执行顺序是: `unshift` => 内置中间件 => `push`。
+
+```js
+export default {
+  dev: {
+    setupMiddlewares: [
+      (middlewares, server) => {
+        middlewares.unshift((req, res, next) => {
+          next();
+        });
+
+        middlewares.push((req, res, next) => {
+          next();
+        });
+      },
+    ],
+  },
+};
+```
+
+一些特殊场景需求可能需要使用服务器 API：
+
+- sockWrite。允许向 HMR 客户端传递一些消息，HMR 客户端将根据接收到的消息类型进行不同的处理。如果你发送一个 "content-changed " 的消息，页面将会重新加载。
+
+```js
+export default {
+  dev: {
+    setupMiddlewares: [
+      (middlewares, server) => {
+        // 添加自定义 watcher 并在文件更新时触发页面刷新
+        watcher.on('change', (changed) => {
+          server.sockWrite('content-changed');
+        });
+      },
+    ],
+  },
+};
+```

package/docs/zh/configure/app/dev/watch-files.mdx

@@ -0,0 +1,59 @@
+---
+sidebar_label: watchFiles
+---
+
+# dev.watchFiles
+
+- **类型：**
+
+```ts
+type WatchFiles = {
+  paths: string | string[];
+  //  chokidar 选项
+  options?: WatchOptions;
+};
+```
+
+- **默认值：** `undefined`
+
+监视指定文件和目录的变化。当文件发生变化时，页面将重新加载。
+
+如果 `dev.hmr` 和 `dev.liveReload` 都设置为 false，则 `watchFiles` 将被忽略。
+
+:::tip
+WatchFiles 中文件发生变化时，不会触发配置文件的重新加载及重新编译。
+:::
+
+### 示例
+
+你可以配置一个 glob 模式 / 目录 / 文件的列表，用于监视文件变化。
+
+```js
+export default {
+  dev: {
+    watchFiles: {
+      // 监视单个文件
+      paths: 'public/demo.txt',
+      // 使用 glob 模式
+      paths: 'src/**/*.txt',
+      // 监视多个文件路径
+      paths: ['src/**/*.txt', 'public/**/*'],
+    },
+  },
+};
+```
+
+你也可以通过传入一个包含 `paths` 和 `options` 属性的对象，来指定 [chokidar](https://github.com/paulmillr/chokidar#api) 选项。
+
+```js
+export default {
+  dev: {
+    watchFiles: {
+      paths: 'src/**/*.txt',
+      options: {
+        usePolling: false,
+      },
+    },
+  },
+};
+```

package/docs/zh/configure/app/dev/write-to-disk.mdx

@@ -0,0 +1,38 @@
+---
+sidebar_label: writeToDisk
+---
+
+# dev.writeToDisk
+
+- **类型：** `boolean | ((filename: string) => boolean)`
+- **默认值：** `(file: string) => !file.includes('.hot-update.')`
+
+用于控制是否将开发环境的构建产物写入到磁盘上。
+
+## 写入内存
+
+你可以选择将构建产物构建产物保存在 dev server 的内存中，从而减少文件操作产生的开销。
+
+只需要将 `dev.writeToDisk` 配置项设置为 `false` 即可：
+
+```ts
+export default {
+  dev: {
+    writeToDisk: false,
+  },
+};
+```
+
+## 匹配部分文件
+
+你也可以将 `dev.writeToDisk` 设置为函数来匹配一部分文件，函数返回 `false` 时不会写入文件，返回值 `true` 时会将文件写入磁盘。
+
+例如，Modern.js 会默认将文件写入磁盘，并排除热更新临时文件：
+
+```ts
+export default {
+  dev: {
+    writeToDisk: (file) => !file.includes('.hot-update.'),
+  },
+};
+```

package/docs/zh/guides/basic-features/data/data-fetch.mdx

@@ -247,7 +247,7 @@ export function UserLayout() {
 如果想获取 `entry1/routes/layout.tsx` 中 `loader` 返回的数据，`routeId` 的值就是 `entry1_layout`。
 
 
-### (WIP)Loading UI
+### Loading UI (Experimental)
 
 :::info
 此功能目前是实验性质，后续 API 可能有调整。

package/docs/zh/guides/basic-features/routes.mdx

@@ -296,7 +296,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 </RootLayout>
 ```
 
-### (WIP)Loading
+### Loading (Experimental)
 
 `routes/` 下每一层目录中，开发者可以创建 `loading.tsx` 文件，默认导出一个 `<Loading>` 组件。
 

package/package.json

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