@modern-js/main-doc 2.54.6 → 2.56.0

package/docs/zh/apis/app/runtime/core/render.mdx

@@ -0,0 +1,43 @@
+---
+title: render
+---
+# render
+
+用于渲染项目组件。
+
+## 使用姿势
+
+```ts
+import { render } from '@modern-js/runtime/browser';
+
+render(<ModernRoot />);
+```
+
+## 函数签名
+
+```ts
+export function render(App: React.ReactElement, id?: HTMLElement | string): Promise<any>;
+```
+
+### 参数
+
+- `App`：通过 [`createRoot`](./create-root) 创建的 ReactElement 实例。
+- `id`：要挂载的 DOM 根元素 id，如 `"root"`。
+
+## 示例
+
+```tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+async function beforeRender() {
+   // todo
+}
+
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```
+

package/docs/zh/apis/app/runtime/ssr/renderStreaming.mdx

@@ -0,0 +1,69 @@
+---
+title: renderStreaming
+---
+
+# renderStreaming
+
+用于 React v18+ Streaming SSR 渲染出可读流, 配合 `createRequestHandler` 使用
+
+## 使用
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderStreaming,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  const stream = await renderStreaming(request, <ServerRoot />, options);
+
+  return new Response(stream, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## 函数签名
+
+```ts
+export type RenderStreaming = (
+  request: Request,
+  serverRoot: React.ReactElement,
+  optinos: RenderOptions,
+) => Promise<ReadableStream>;
+```
+
+## 示例
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderStreaming,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  // do something before render
+  const stream = await renderStreaming(request, <ServerRoot />, options);
+
+  // docs: https://developer.mozilla.org/en-US/docs/Web/API/TransformStream
+  const transformStream = new TransformStream({
+    transform(chunk, controller) {
+      // do some transform
+    },
+  });
+
+  stream.pipeThrough(transformStream);
+
+  return new Response(transformStream.readable, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```

package/docs/zh/apis/app/runtime/ssr/renderString.mdx

@@ -0,0 +1,62 @@
+---
+title: renderString
+---
+
+# renderString
+
+用于 React String SSR 渲染出字符串，配合 `createRequestHandler` 使用
+
+## 使用
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  const body = await renderString(request, <ServerRoot />, options);
+
+  return new Response(body, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## 函数签名
+
+```ts
+export type RenderString = (
+  request: Request,
+  serverRoot: React.ReactElement,
+  optinos: RenderOptions,
+) => Promise<string>;
+```
+
+## 示例
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  // do something before render
+  const body = await renderString(request, <ServerRoot />, options);
+
+  const newBody = body + '<div>Byte-Dance</div>';
+
+  return new Response(newBody, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```

package/docs/zh/apis/app/runtime/ssr/requestHandler.mdx

@@ -0,0 +1,47 @@
+---
+title: createRequestHandler
+---
+
+# createRequestHandler
+
+用于自定义 Server-Side Rendering 入口返回 requestHandler
+
+## 使用
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  const body = await renderString(request, <ServerRoot />, options);
+
+  return new Response(body, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## 函数签名
+
+```ts
+export type HandleRequest = (
+  request: Request,
+  ServerRoot: React.ComponentType
+  options: HandleRequestOptions,
+) => Promise<Response>;
+
+export type RequestHandler = (
+  request: Request,
+  options: RequestHandlerOptions,
+) => Promise<Response>;
+
+export type CreateRequestHandler = (
+  handleRequest: HandleRequest,
+) => Promise<RequestHandler>;
+```

package/docs/zh/components/debug-app.mdx

@@ -5,8 +5,9 @@ $ pnpm run dev
 
 > modern dev
 
-info    Starting dev server...
-ready   Client compiled in 50 ms
+  Modern.js Framework v2.55.0
+
+ready   Client compiled in 0.86 s
 
   > Local:    http://localhost:8080/
   > Network:  http://192.168.0.1:8080/

package/docs/zh/configure/app/dev/client.mdx

@@ -35,7 +35,7 @@ const defaultConfig = {
   port: '',
   host: location.hostname,
   protocol: location.protocol === 'https:' ? 'wss' : 'ws',
-  overlay: true,
+  overlay: false,
 };
 ```
 

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/configure/app/output/ssg.mdx

@@ -9,6 +9,10 @@ sidebar_label: ssg
 
 开启**自控式路由**或**约定式路由** SSG 功能的配置。
 
+:::info 开启 SSG 功能
+此配置需要在开启 SSG 功能情况下才会生效。请阅读 [静态站点生成](/guides/advanced-features/ssg) 文档了解如何开启 SSG 功能。
+:::
+
 :::info 客户端路由
 相关内容可以查看[路由方案](/guides/basic-features/routes)。
 

package/docs/zh/configure/app/source/enable-async-entry.mdx

@@ -35,15 +35,15 @@ export default defineConfig({
 node_modules
   └─ .modern-js
      └─ main
-        ├─ bootstrap.jsx  # 真正的入口代码
-        ├─ index.js      # 异步入口文件（asynchronous boundary）
+        ├─ bootstrap.jsx  # 异步入口文件（asynchronous boundary）
+        ├─ index.js      # 真正的入口代码
         └─ index.html
 ```
 
-其中 `index.js` 的内容如下：
+其中 `bootstrap.js` 的内容如下：
 
 ```js
-import('./bootstrap.jsx');
+import('./index.jsx');
 ```
 
 此时，就可以在当前页面中消费任意的远程模块了。

package/docs/zh/configure/app/source/enable-custom-entry.mdx

@@ -0,0 +1,41 @@
+---
+sidebar_label: enableCustomEntry
+---
+
+# source.enableCustomEntry
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+该选项用于使用 Modern.js 自定义入口场景。
+
+开启此选项后，Modern.js 将使用 `src/entry.[jt]sx` 文件作为项目的入口， 具体使用姿势可参考[页面入口](/guides/concept/entries.html)。
+
+## 示例
+
+首先，在配置文件中开启此选项：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    enableCustomEntry: true,
+  },
+});
+```
+
+创建 `src/entry.tsx` 文件：
+
+```tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+async function beforeRender() {
+   // todo
+}
+
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```

package/docs/zh/guides/advanced-features/ssr/cache.mdx

@@ -55,10 +55,10 @@ export interface CacheControl {
 ```ts
 export type CacheOptionProvider = (
   req: IncomingMessage,
-) => Promise<CacheControl> | CacheControl;
+) => Promise<CacheControl | false> | CacheControl | false;
 ```
 
-有时开发者需要通过 req 来自定义缓存 key，可以配置为函数的形式进行处理, 例如以下代码：
+有时开发者需要通过 req 来自定义缓存 key，或者特定 url 时缓存不生效，可以配置为函数的形式进行处理, 例如以下代码：
 
 ```ts title="server/cache.ts"
 
@@ -69,6 +69,10 @@ const provider: CacheOptionProvider = (req) => {
 
   const key = computedKey(url, headers, ...);
 
+  if(url.includes('no-cache=1')) {
+    return false;
+  }
+
   return {
     maxAge: 500, // ms
     staleWhileRevalidate: 1000, // ms

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>` 组件。