@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

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

@@ -26,7 +26,6 @@ MODERNJS_DEPLOY=netlify npx modern deploy
 在 Modern.js 官方支持的部署平台中部署时，无需指定环境变量。
 :::
 
-
 ## ModernJS 内置 Node.js 服务器
 
 ### 单仓库项目
@@ -54,8 +53,8 @@ You can preview this build by `node .output/index`
 ```
 PORT=3000 node .output/index
 ```
-:::
 
+:::
 
 ### Monorepo
 
@@ -67,7 +66,7 @@ PORT=3000 node .output/index
 {
   "scripts": {
     "build:packages": "pnpm --filter 'app^...' run build",
-    "deploy": "pnpm run build:packages && modern deploy",
+    "deploy": "pnpm run build:packages && modern deploy"
   }
 }
 ```
@@ -78,7 +77,7 @@ PORT=3000 node .output/index
 {
   "scripts": {
     "build:packages": "rush rebuild --to-except app",
-    "deploy": "rushx build:packages && modern deploy",
+    "deploy": "rushx build:packages && modern deploy"
   }
 }
 ```
@@ -102,6 +101,7 @@ Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现
 ```
 
 在 `netlify.toml` 中添加以下内容：
+
 ```toml
 [build]
   publish = "dist"
@@ -131,14 +131,12 @@ Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现
 ```
 
 :::info
+
 1. 目前 Modern.js 还不支持在 Netlify Edge Functions 进行部署，我们将在后续的版本中支持。
 2. 你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr)。
 
 :::
 
-
-
-
 ### Monorepo 项目
 
 :::info
@@ -169,7 +167,7 @@ Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现
 {
   "scripts": {
     "build:packages": "pnpm --filter 'app^...' run build",
-    "deploy": "pnpm run build:packages && modern deploy",
+    "deploy": "pnpm run build:packages && modern deploy"
   }
 }
 ```
@@ -231,7 +229,6 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 1. 当前，Modern.js 还不支持在 Vercel 平台上部署 BFF 项目，我们将在后续的版本中支持。
 2. 函数运行的 node.js 版本由项目在 Vercel 平台配置决定。
 
-
 :::info
 你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr)。
 
@@ -261,10 +258,11 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 
 <img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/vercel-root-directory.png" />
 
-将 Node.js 运行时设置为 `18.x`：
+将 Node.js 运行时设置为 `20.x`：
+
 ```json title="package.json"
 "engines": {
-  "node": "18.x"
+  "node": "20.x"
 },
 ```
 
@@ -274,12 +272,13 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 {
   "scripts": {
     "build:packages": "pnpm --filter 'app^...' run build",
-    "deploy": "pnpm run build:packages && modern deploy",
+    "deploy": "pnpm run build:packages && modern deploy"
   }
 }
 ```
 
 在 `packages/app/vercel.json` 文件中添加以下内容：
+
 ```json title="vercel.json"
 {
   "buildCommand": "npm run deploy",
@@ -291,23 +290,25 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 
 ## Github Pages
 
-如果你要为一个仓库常见 Github 页面，并且你没有自定义域名，则该页面的 URL 将会是以下格式：`http://<username>.github.io/<repository-name>`，所以需要在 `modern.config.ts` 中添加
+如果你要为一个仓库创建 Github 页面，并且你没有自定义域名，则该页面的 URL 将会是以下格式：`http://<username>.github.io/<repository-name>`，所以需要在 `modern.config.ts` 中添加
 以下配置：
+
 ```ts
 import { defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
   //...
-  server:{
-    baseUrl: "/<repository-name>"
+  server: {
+    baseUrl: '/<repository-name>',
   },
   output: {
-    assetPrefix: "/<repository-name>",
-  }
+    assetPrefix: '/<repository-name>',
+  },
 });
 ```
 
 Github Pages 支持两种部署方式，通过分支部署或通过 Github Actions 部署，如果通过分支部署，可以使用以下步骤：
+
 1. 在 github 仓库中，选择 `Settings > Pages > Source > Deploy from a branch`。
 2. 安装 `gh-pages` 依赖作为开发依赖。
 3. 在 package.json 的 `scripts` 中添加 `"deploy:gh-pages": "MODERNJS_DEPLOY=ghPages modern deploy && gh-pages -d .output"`。
@@ -322,7 +323,6 @@ Github Pages 支持两种部署方式，通过分支部署或通过 Github Actio
 
 如果通过 Github Actions 部署，可以选择 Settings > Pages > Source > GitHub Actions，并在项目中添加 workflow 文件，可参考[示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
 
-
 ## 自建 Node.js 服务器
 
 通常情况下，我们推荐使用 Modern.js 内置的 Node.js 服务器来部署应用，它支持托管纯前端项目或者全栈项目，并且保证在开发和生产环境下的表现一致。
@@ -367,10 +367,14 @@ const app = new Koa();
 app.use(async (ctx, next) => {
   if (ctx.path.startsWith('/static')) {
     ctx.type = mime.lookup(ctx.path);
-    ctx.body = fs.createReadStream(path.resolve(__dirname, `.output${ctx.path}`));
+    ctx.body = fs.createReadStream(
+      path.resolve(__dirname, `.output${ctx.path}`),
+    );
   } else if (ctx.path === '/') {
     ctx.type = 'html';
-    ctx.body = fs.createReadStream(path.resolve(__dirname, '.output/html/main/index.html'));
+    ctx.body = fs.createReadStream(
+      path.resolve(__dirname, '.output/html/main/index.html'),
+    );
   }
 });
 app.listen(3000);

package/docs/zh/guides/basic-features/env-vars.mdx

@@ -142,7 +142,7 @@ export default defineConfig({
   source: {
     globalVars: {
       'process.env.VERSION': process.env.VERSION,
-    }.
+    },
   },
 });
 ```

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

@@ -35,7 +35,7 @@ Modern.js 约定，在 `src/` 或入口目录下，可以创建 `Document.[jt]sx
 
 ### HTML 组件
 
-Modern.js 提供了一些列渲染页面的组件，用来帮助开发者生成模板，可以从 `@modern-js/runtime/document` 中使用这些组件：
+Modern.js 提供了一系列渲染页面的组件，用来帮助开发者生成模板，可以从 `@modern-js/runtime/document` 中使用这些组件：
 
 ```tsx
 import { Html, Body, Root, Head, Scripts } from '@modern-js/runtime/document';
@@ -154,7 +154,7 @@ export default function Document(): React.ReactElement {
 你可以使用 `<Scripts>` 组件，将构建生成的 `<script>` 标签插入到 `<body>` 标签内：
 
 ```tsx
-import React, { useContext } from 'react';
+import React from 'react';
 import { Html, Root, Head, Body, Scripts } from '@modern-js/runtime/document';
 
 export default function Document(): React.ReactElement {

package/docs/zh/guides/basic-features/output-files.mdx

@@ -47,8 +47,8 @@ Modern.js 提供了多个配置项来修改产物目录和产物名称，你可
 - 通过 [output.filename](/configure/app/output/filename) 来修改产物的文件名。
 - 通过 [output.distPath](/configure/app/output/dist-path) 来修改产物的输出路径。
 - 通过 [output.legalComments](/configure/app/output/legal-comments) 来修改 License 文件的生成方式。
-- 通过 [output.disableSourceMap](/configure/app/output/disable-source-map) 来移除 Source Map 文件。
-- 通过 [html.disableHtmlFolder](/configure/app/html/disable-html-folder) 移除 HTML 产物对应的文件夹。
+- 通过 [output.sourceMap](/configure/app/output/source-map) 来移除 Source Map 文件。
+- 通过 [html.outputStructure](/configure/app/html/output-structure) 移除 HTML 产物对应的文件夹。
 
 ## 静态资源
 
@@ -112,7 +112,7 @@ export default {
     },
   },
   html: {
-    disableHtmlFolder: true,
+    outputStructure: 'flat',
   },
 };
 ```

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

@@ -1 +1 @@
-["ssr", "streaming-ssr", "ssr-cache", "ssg", "before-render"]
+["overview", "ssr", "streaming-ssr", "ssr-cache", "ssg", "rsc", "before-render"]

package/docs/zh/guides/basic-features/render/before-render.mdx

@@ -1,16 +1,16 @@
-# 渲染预处理 (Render Preprocessing)
+# 渲染预处理
 
 在某些场景下，应用需要在渲染前执行预处理操作。Modern.js 推荐使用 **[Runtime 插件 (Runtime Plugin)](/plugin/introduction.html#runtime-插件)** 来实现这类逻辑。
 
 ## 定义 Runtime 插件
 
 ```ts
-import type { RuntimePluginFuture } from '@modern-js/runtime';
+import type { RuntimePlugin } from '@modern-js/runtime';
 
-const myRuntimePlugin = (): RuntimePluginFuture => ({
+const myRuntimePlugin = (): RuntimePlugin => ({
   name: 'my-runtime-plugin',
-  setup: (api) => {
-    api.onBeforeRender((context) => {
+  setup: api => {
+    api.onBeforeRender(context => {
       // 在渲染前执行的逻辑
       console.log('Before rendering:', context);
     });
@@ -35,23 +35,24 @@ export default defineRuntimeConfig({
 
 ## 应用场景 -- 全局数据注入
 
-通过 `onBeforeRender` 钩子的 `context` 参数，可以向应用注入全局数据。应用的组件可以通过 `useRuntimeContext` Hook 访问这些数据。
+通过 `onBeforeRender` 钩子的 `context` 参数，可以向应用注入全局数据。应用的组件可以通过 `use(RuntimeContext)` Hook 访问这些数据。
 
 :::info
 
 此功能在以下场景中特别有用：
-* 需要页面级前置数据的应用
-* 自定义数据注入流程
-* 框架迁移场景（例如从 Next.js 迁移）
+
+- 需要页面级前置数据的应用
+- 自定义数据注入流程
+- 框架迁移场景（例如从 Next.js 迁移）
 
 :::
 
 **定义数据注入插件**
 
 ```ts
-import type { RuntimePluginFuture } from '@modern-js/runtime';
+import type { RuntimePlugin } from '@modern-js/runtime';
 
-const dataInjectionPlugin = (): RuntimePluginFuture => ({
+const dataInjectionPlugin = (): RuntimePlugin => ({
   name: 'data-injection-plugin',
   setup: api => {
     api.onBeforeRender(context => {
@@ -67,10 +68,11 @@ export default dataInjectionPlugin;
 **在组件中使用注入的数据**
 
 ```tsx
-import { useRuntimeContext } from '@modern-js/runtime';
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
 
 export default function MyComponent() {
-  const context = useRuntimeContext();
+  const context = use(RuntimeContext);
   const { message } = context;
 
   return <div>{message}</div>;
@@ -82,9 +84,9 @@ export default function MyComponent() {
 在 SSR 场景下，浏览器端可以获取服务端渲染期间通过 `onBeforeRender` 注入的数据。开发者可以根据需求决定是否在浏览器端重新获取数据来覆盖服务端数据。
 
 ```ts
-import type { RuntimePluginFuture } from '@modern-js/runtime';
+import type { RuntimePlugin } from '@modern-js/runtime';
 
-const dataInjectionPlugin = (): RuntimePluginFuture => ({
+const dataInjectionPlugin = (): RuntimePlugin => ({
   name: 'data-injection-plugin',
   setup: api => {
     api.onBeforeRender(context => {
@@ -104,12 +106,3 @@ const dataInjectionPlugin = (): RuntimePluginFuture => ({
 
 export default dataInjectionPlugin;
 ```
-
-## 兼容性说明
-
-在 Modern.js 的早期版本中，支持通过 `routes/layout.tsx` 中的 `init` 钩子以及 `App.init` 方法来添加渲染预处理逻辑。这些方式目前仍然**被支持**，但我们**强烈推荐**使用 Runtime 插件实现。
-
-:::warning
-
-未来版本中，`routes/layout.tsx` 的 `init` 钩子和 `App.init` 方法将逐步**废弃**。建议尽早迁移到 Runtime 插件方案。
-:::

package/docs/zh/guides/basic-features/render/overview.mdx

@@ -0,0 +1,52 @@
+---
+title: 渲染模式总览
+---
+
+# 渲染模式总览
+
+Modern.js 支持多种渲染模式，不同的渲染模式适用于不同的场景。选择合适的渲染模式可以显著提升应用的性能和用户体验。
+
+## 渲染模式速览
+
+| 渲染模式 | 特点 | 适用场景 |
+|---------|------|---------|
+| **CSR** | 在浏览器端执行 JavaScript 渲染页面 | 交互性强、对 SEO 要求不高的应用 |
+| **SSR** | 在服务端预先渲染完整 HTML 页面 | 对首屏性能和 SEO 要求高的网站 |
+| **Streaming SSR** | 边渲染边返回，更快显示初始 UI | 需要更快首屏感知速度的应用（**SSR 默认模式**） |
+| **RSC** | 组件在服务端渲染，减少客户端 JS 体积；数据与组件逻辑高内聚，减少状态传递 | 追求极致性能、需要减少客户端代码的项目 |
+| **SSG** | 构建时生成静态页面，可被 CDN 缓存 | 内容相对静态的网站，如博客、文档站点 |
+
+## 性能对比
+
+| 渲染技术 | 核心优势 | 主要瓶颈 |
+|---------|---------|---------|
+| **SSR** | 服务端预渲染，有利于 SEO | 需等待所有数据加载完成才能响应 |
+| **Streaming SSR** | 边渲染边返回，更快首屏 | JS 体积仍然较大 |
+| **Streaming SSR + RSC** | 减少客户端 JS 体积 | - |
+
+## 如何选择
+
+### 快速决策
+
+- **内容静态 + 需要 SEO** → **SSG**
+- **需要 SEO + 首屏性能** → **Streaming SSR**（默认）
+- **追求极致性能** → **Streaming SSR + RSC**
+- **CSR 项目渐进优化** → **CSR + RSC**
+- **高度交互 + 无需 SEO** → **CSR**
+
+### 组合使用
+
+Modern.js 支持多种渲染模式组合使用：
+
+- **Streaming SSR + RSC**：流式渲染 + 减少客户端代码
+- **SSG + SSR**：部分页面静态，部分页面动态
+- **CSR + RSC**：客户端渲染 + 部分 Server Component
+
+
+## 相关文档
+
+- [服务端渲染（SSR）](/guides/basic-features/render/ssr)
+- [流式服务端渲染（Streaming SSR）](/guides/basic-features/render/streaming-ssr)
+- [React Server Components（RSC）](/guides/basic-features/render/rsc)
+- [静态站点生成（SSG）](/guides/basic-features/render/ssg)
+- [渲染缓存](/guides/basic-features/render/ssr-cache)