@modern-js/main-doc 2.60.6 → 2.62.0

package/docs/zh/guides/advanced-features/source-build.mdx

@@ -124,13 +124,10 @@ Project reference 提供了以下能力：
 
 ### 示例
 
-在上文的例子中，由于 app 引用了 lib 子项目，我们需要在 app 的 `tsconfig.json` 内配置 `composite` 和 `references`，并指向 lib 对应的相对目录：
+在上文的例子中，由于 app 引用了 lib 子项目，我们需要在 app 的 `tsconfig.json` 内配置 `references`，并指向 lib 对应的相对目录：
 
 ```json title="app/tsconfig.json"
 {
-  "compilerOptions": {
-    "composite": true
-  },
   "references": [
     {
       "path": "../lib"
@@ -139,6 +136,16 @@ Project reference 提供了以下能力：
 }
 ```
 
+同时，需要在 lib 子项目的 `tsconfig.json` 内配置 `composite` 为 `true`：
+
+```json title="lib/A/tsconfig.json"
+{
+  "compilerOptions": {
+    "composite": true
+  },
+}
+```
+
 添加以上两个选项后，project reference 就已经配置完成了，你可以重新启动 VS Code 来查看配置以后的效果。
 
 注意以上只是一个最简单的例子，在实际的 monorepo 项目中，可能会有更复杂的依赖关系，你需要添加完整的 `references` 配置，才能使上述功能正确运作。

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

@@ -13,11 +13,10 @@ sidebar_position: 15
 目前 Modern.js 仅支持在 Node.js 环境中运行，未来将提供更多运行时环境的支持。
 :::
 
-
 ## 构建部署产物
 
 执行 `modern deploy` 命令将自动输出部署产物。此过程包括优化 Bundler 构建产物及产物依赖，检测当前部署平台，并自动生成可以在该平台运行的产物。
-如果你希望在本地生成并测试特定部署平台的产物，可以通过设置环境变量来指定平台:
+如果你希望在本地生成并测试特定部署平台的产物，可以通过设置环境变量来指定平台：
 
 ```bash
 MODERNJS_DEPLOY=netlify npx modern deploy
@@ -27,8 +26,7 @@ MODERNJS_DEPLOY=netlify npx modern deploy
 在 Modern.js 官方支持的部署平台中部署时，无需指定环境变量。
 :::
 
-
-## Node.js
+## ModernJS 内置 Node.js 服务器
 
 ### 单仓库项目
 
@@ -223,7 +221,6 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 }
 ```
 
-
 ### Monorepo 项目
 
 :::info
@@ -277,5 +274,106 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 提交你的代码，使用 Vercel 平台部署即可。
 
 
+## 自建 Node.js 服务器
+
+通常情况下，我们推荐使用 Modern.js 内置的 Node.js 服务器来部署应用，它支持托管纯前端项目或者全栈项目，并且保证在开发和生产环境下的表现一致。
+
+如果你的项目是纯前端项目，也可以通过自建 Node.js 服务器来部署应用，以下用一个 Koa 服务器的示例来演示如何托管一个纯前端项目的产物。
+
+例如你有一个 Node.js 服务器的仓库，你可以将项目的产物复制到该仓库下，现在结构如下：
+
+```bash
+.
+├── .output
+│   ├── html
+│   └── static
+└── server.js
+```
+
+在 `server.js` 中，假定有如下代码：
+
+```ts title="server.js"
+import Koa from 'koa';
+
+const app = new Koa();
+app.use(async (ctx, next) => {
+  ctx.body = 'Hello Modern.js';
+});
+app.listen(3000);
+```
+
+现在，你可以新增部分代码，将静态资源和 HTML 文件的访问逻辑添加到 `server.js` 中。这里需要通过 `mime-types` 包来获取静态资源的 MIME 类型，因此我们先安装依赖：
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command="add mime-types" />
+
+```ts title="server.js"
+const Koa = require('koa');
+const fs = require('fs');
+const path = require('path');
+const mime = require('mime-types');
+
+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}`));
+  } else if (ctx.path === '/') {
+    ctx.type = 'html';
+    ctx.body = fs.createReadStream(path.resolve(__dirname, '.output/html/main/index.html'));
+  }
+});
+app.listen(3000);
+```
+
+:::note
+以上代码是最基础的例子，你的应用可能是多入口的，需要根据不同的路径访问不同的 HTML 文件，自建 Node.js 服务器也会存在更多的逻辑。
+:::
+
+需要注意的是，如果你的项目中使用 Modern.js 约定式路由，或是使用 React Router 自行搭建了浏览器端路由，你必须通过正确的 `baseURL` 来访问 HTML 文件。
+
+在 Modern.js 中，默认的 `baseURL` 是 `'/'`，你可以通过在 `modern.config.ts` 中修改 [`server.baseUrl`](/configure/app/server/base-url) 来配置。
+
+:::danger
+存在浏览器路由的项目，永远无法通过 `/index.html` 路径来访问到 HTML 文件。
+:::
+
+## Nignx
+
+Nginx 是一个高性能的 HTTP 和反向代理服务器，它可以处理静态文件、反向代理、负载均衡等功能。在 Nginx 上部署，通常需要配置 `nginx.conf` 文件。
+
+如果你的项目是纯前端项目，也可以通过 Nginx 来部署应用，以下提供一个 Nginx 配置的示例来演示如何托管一个纯前端项目的产物。
+
+```conf title="nginx.conf"
+# user [user] [group];
+worker_processes 1;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    include       mime.types;
+    default_type  application/octet-stream;
+
+    server {
+        listen 8080;
+        server_name localhost;
+
+        location / {
+            # root [projectPath]/.output/html/main;
+            index index.html;
+            try_files $uri $uri/ =404;
+        }
+
+        location /static {
+          # alias [projectPath]/.output/static;
+        }
+    }
+}
+```
 
+在上述配置中，你需要将 `[projectPath]` 替换为你的项目路径，将 `[user]` 和 `[group]` 替换为你当前的用户和用户组。
 
+你可以将上述配置复制到 Nginx 安装目录的 `nginx.conf` 文件中，然后启动 Nginx 服务。你也可以通过 `nginx -c` 启动指定路径下的配置文件，此时你需要额外保证 `include` 指令配置的路径正确。

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

@@ -118,7 +118,29 @@ Modern.js 也支持通过 [`server.ssr`](/configure/app/server/ssr) 配置项中
 
 ### 组件渲染报错
 
-当组件渲染报错时，Modern.js 会自动降级到 CSR 模式，并重新发起数据请求。如果重新渲染仍然出错，则展示 `<ErrorBoundary>` 组件。
+如果 Data Loader 执行正常，但组件渲染报错时，SSR 渲染将会部分或完全失败，例如以下代码：
+
+```tsx
+import { Await, useLoaderData } from '@modern-js/runtime/router';
+import { Suspense } from 'react';
+
+const Page = () => {
+  const data = useLoaderData();
+  const isNode = typeof window === 'undefined';
+  const undefinedVars = data.unDefined;
+  const definedVars = data.defined;
+
+  return (
+    <div>
+      {isNode ? undefinedVars.msg : definedVars.msg}
+    </div>
+  );
+};
+
+export default Page;
+```
+
+此时，Modern.js 会将页面降级为 CSR，并利用 Data Loader 中已有的数据渲染。如果重新渲染仍然出错，则展示 `<ErrorBoundary>` 组件。
 
 :::tip
 组件渲染报错的行为，不会受到 `loaderFailureMode` 的影响，也不会在浏览器端执行 Client Loader。

package/docs/zh/guides/concept/entries.mdx

@@ -12,7 +12,7 @@ sidebar_position: 1
 
 在 Modern.js 应用中，每一个入口对应一个独立的页面，也对应一条服务端路由。默认情况下，Modern.js 会基于目录约定来自动确定页面的入口，同时也支持通过配置项来自定义入口。
 
-Modern.js 提供的很多配置项都是以入口为维度进行划分的，比如页面标题、HTML 模板、页面 Meta 信息、是否开启 SSR/SSG、服务端路由规则等。
+Modern.js 提供的很多配置项都是以入口为维度进行划分的，比如页面标题、HTML 模板、页面 Meta 信息、是否开启 SSR/SSG、服务端路由规则等。如果你希望了解更多关于入口的技术细节，请参考[深入了解](#深入了解)章节的内容。
 
 ## 单入口与多入口
 
@@ -239,6 +239,57 @@ export default defineConfig({
 值得注意的是，默认情况下，Modern.js 认为通过配置指定的入口是**框架模式入口**，将自动生成真正的编译入口。如果你的应用是从 Webpack 或 Vite 等构建工具迁移到 Modern.js 框架时，你通常需要在入口配置中开启 `disableMount` 选项，此时 Modern.js 认为该入口是**构建模式入口**。
 
 
+## 深入了解
+
+页面入口的概念衍生自 webpack 的入口（Entrypoint）概念，其主要用于配置 JavaScript 或其他模块在应用启动时加载和执行。webpack 对于网页应用的 [最佳实践](https://webpack.docschina.org/concepts/entry-points/#multi-page-application) 通常将入口与 HTML 产物对应，即每增加一个入口最终就会在产物中生成一份对应的 HTML 文件。入口引入的模块会在编译打包后生成多个 Chunk 产物，例如对于 JavaScript 模块最终可能会生成数个类似 `dist/static/js/index.ea39u8.js` 的文件产物。
+
+需要注意区分入口、路由等概念之间的关系：
+
+- **入口**：包含多个用于启动时执行的模块。
+- **客户端路由**：在 Modern.js 中通常由 `react-router` 实现，通过 History API 判断浏览器当前 URL 决定加载和显示哪个 React 组件。
+- **服务端路由**：服务端可以模仿 [devServer 的行为](https://webpack.docschina.org/configuration/dev-server/#devserverhistoryapifallback)，将 index.html 页面代替所有 404 响应被返回以实现客户端路由，也可以自行实现任何路由逻辑。
+
+它们的对应关系如下：
+
+- 每个 webpack 网站项目可以包含多个入口
+- 每个入口包含若干个模块（源码文件）
+- 每个入口通常对应一个 HTML 文件产物和若干其它产物。
+- 每个 HTML 文件可以包含多个客户端路由方案（比如在页面中同时使用 `react-router` 和 `@tanstack/react-router`）。
+- 每个 HTML 文件可以被多个服务端路由对应。
+- 每个 HTML 文件可以包含多个客户端路由，当访问单入口应用的不同路由时实际使用的是同一个 HTML 文件。
+
+## 常见问题
+
+1. **`react-router` 定义的每个客户端路由会分别生成一个 HTML 文件吗？**
+
+不会。每个入口通常只会生成一个 HTML 文件，单个入口中如果定义多个客户端路由系统会共用这一个 HTML 文件。
+
+2. **约定式路由的 `routes/` 目录下每个 `page.tsx` 文件都会生成一个 HTML 文件吗？**
+
+不是。约定式路由是基于 `react-router` 实现的客户端路由方案，其约定 `routes/` 目录下每个 `page.tsx` 文件都会对应生成一个 `react-router` 的客户端路由。`routes/` 本身作为一个页面入口，对应最终产物中的一个 HTML 文件。
+
+3. **服务端渲染（SSR）的项目是否会构建多份 HTML 产物？**
+
+在使用服务端渲染应用时并不必须在编译时生成一份 HTML 产物，它可以只包含用于渲染的服务端 JavaScript 产物。此时 `react-router` 将在服务端运行和调度路由，并在每次请求时渲染并响应 HTML 内容。
+
+而 Modern.js 在编译时仍会为每个入口生成包含 HTML 文件的完整的客户端产物，用于在服务端渲染失败时降级为客户端渲染使用。
+
+另一个特殊情况是使用静态站点生成（SSG）的项目，即使是使用约定式路由搭建的单入口 SSG 应用，Modern.js 也会在 webpack 的流程外为每个 `page.tsx` 文件生成一份单独的 HTML 文件。
+
+需要注意的是即使开启服务端渲染，React 通常仍需要执行水合阶段并在前端执行 `react-router` 的路由。
+
+4. **单入口应用是否存在输出多个 HTML 文件的例外情况？**
+
+你可以自行配置 [html-rspack-plugin](https://rspack.dev/zh/plugins/rspack/html-rspack-plugin#%E7%94%9F%E6%88%90%E5%A4%9A%E4%B8%AA-html-%E6%96%87%E4%BB%B6) 为每个入口生成多个 HTML 产物，或使多个入口共用一个 HTML 产物。
+
+5. **什么叫多页应用（Multi-Page Application）？**
+
+多页应用的 “页面” 指的是静态的 HTML 文件。
+一般可以将任何包含多个入口、多个 HTML 文件产物的网页应用称为多页应用。
+狭义的多页应用可能不包含客户端路由、仅通过 `<a>` 之类的标签元素进行 HTML 静态页面之间的跳转，但实践中上多页应用也经常需要为其入口配置客户端路由以满足不同需求。
+
+相反地，通过 `react-router` 定义多个路由的单入口应用因为只生成一个 HTML 文件产物，所以被称为单页应用（Single Page Application）。
+
 ## 弃用功能
 
 目前，如果入口所在的目录满足以下条件，也会成为应用入口。
@@ -267,6 +318,3 @@ export default (App: React.ComponentType, bootstrap: () => void) => {
 ### 构建模式入口
 
 当入口目录中存在 `index.[jt]sx`(即将废弃) 并且没有通过 `export default` 导出函数时，该入口也将被认为是构建模式入口。
-
-
-

package/docs/zh/guides/get-started/introduction.mdx

@@ -5,42 +5,7 @@ sidebar_position: 1
 
 # Modern.js 介绍
 
-**Modern.js 是字节跳动 Web 工程体系的开源版本**，它提供多个解决方案，来帮助开发者解决不同研发场景下的问题。
-
-目前 Modern.js 包含两个解决方案，分别面向 Web 应用开发场景 和 npm 包开发场景：
-
-import { SolutionCards } from '@site/src/components/SolutionCards';
-
-<SolutionCards
-  cards={[
-    {
-      title: 'Modern.js Framework',
-      description: '基于 React 的渐进式 Web 开发框架',
-      link: 'http://modernjs.dev/',
-    },
-    {
-      title: 'Modern.js Module',
-      description: '易用、高性能的 npm 包开发方案',
-      link: 'http://modernjs.dev/module-tools/',
-    },
-  ]}
-/>
-
-## 关于文档
-
-**当前文档站对应的是 Modern.js 框架**，适用于开发 Web 应用。
-
-- 如果你需要开发一个 npm 包，请移步 [Modern.js Module 文档](https://modernjs.dev/module-tools)。
-- 如果你需要一个构建工具来打包 Web 应用，请移步 [Rsbuild 文档](https://rsbuild.dev/)。
-- 如果你需要开发一个文档站点，推荐使用 [Rspress 文档](https://rspress.dev/)。
-
-:::tip
-由于 Modern.js 框架的使用最为广泛，在本文档站中，我们会省略「框架」，直接称其为 Modern.js。
-:::
-
-## Modern.js 框架
-
-**Modern.js 框架是一个基于 React 的渐进式 Web 开发框架**。在字节跳动内部，我们将 Modern.js 封装为上层框架，并支撑了数千个 Web 应用的研发。
+**Modern.js 是一个基于 React 的渐进式 Web 开发框架**。在字节跳动内部，我们将 Modern.js 封装为上层框架，并支撑了数千个 Web 应用的研发。
 
 Modern.js 能为开发者提供极致的**开发体验（Development Experience）**，让应用拥有更好的**用户体验（User Experience）**。
 

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

@@ -12,7 +12,7 @@ Modern.js 框架默认集成了一些社区中流行的库和开发工具。
 
 Modern.js 使用 [React 18](https://react.dev/) 来构建用户界面，同时也兼容 React 17。
 
-Modern.js 底层的 Rsbuild 支持构建 Vue 应用，如果你需要使用 Vue，可以参考 [Rsbuild - Vue](https://rsbuild.dev/zh/guide/framework/vue3)。
+Modern.js 底层的 Rsbuild 支持构建 Vue 应用，如果你需要使用 Vue，可以参考 [Rsbuild - Vue](https://rsbuild.dev/zh/guide/framework/vue)。
 
 ## 路由
 

package/package.json

@@ -15,17 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.60.6",
+  "version": "2.62.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "2.60.6"
+    "@modern-js/sandpack-react": "2.62.0"
   },
   "devDependencies": {
-    "@rspress/shared": "1.35.2",
+    "@rspress/shared": "1.35.4",
     "@types/fs-extra": "9.0.13",
     "@types/node": "^16",
     "classnames": "^2",
@@ -33,7 +33,7 @@
     "fs-extra": "^10",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "rspress": "1.35.2",
+    "rspress": "1.35.4",
     "ts-node": "^10.9.1",
     "typescript": "^5"
   },

package/src/i18n/enUS.ts

@@ -23,13 +23,6 @@ export const EN_US = {
   featureDesc6:
     'Launch with zero configuration, then everything is configurable.',
 
-  // Solutions
-  solutions: 'Solutions',
-  solutionsDesc1: 'A progressive React framework for web development.',
-  solutionsDesc2: 'A powerful solution for npm package development.',
-  solutionsDesc3: 'An Rspack-based build tool for web development.',
-  solutionsDesc4: 'A fast Rspack-based static site generator',
-
   // Footer
   guide: 'Guide',
   topic: 'Topic',

package/src/i18n/zhCN.ts

@@ -23,13 +23,6 @@ export const ZH_CN: Record<keyof typeof EN_US, string> = {
   feature6: '易于配置',
   featureDesc6: '以零配置启动，然后一切皆可配置。',
 
-  // Solutions
-  solutions: '解决方案',
-  solutionsDesc1: '基于 React 的渐进式 Web 开发框架。',
-  solutionsDesc2: '简单、高性能的 npm 包开发方案。',
-  solutionsDesc3: '基于 Rspack 的 Web 构建工具。',
-  solutionsDesc4: '基于 Rspack 的静态站点生成器。',
-
   // Footer
   guide: '指南',
   topic: '专题',

package/src/pages/index.tsx

@@ -1,6 +1,6 @@
 import clsx from 'clsx';
 import { useEffect } from 'react';
-import { Helmet, useLang, useLocation } from 'rspress/runtime';
+import { Helmet, useLocation } from 'rspress/runtime';
 import ContentCard from '../components/ContentCard';
 import { FeatureLayout } from '../components/FeatureLayout';
 import Footer from '../components/Footer';
@@ -92,22 +92,6 @@ export default function Home() {
     },
   ];
 
-  const lang = useLang();
-  const solutions = [
-    {
-      id: 'framework',
-      title: 'Modern.js Framework',
-      href: useUrl('/guides/get-started/introduction'),
-      desc: t('solutionsDesc1'),
-    },
-    {
-      id: 'module',
-      title: 'Modern.js Module',
-      href: `https://modernjs.dev/module-tools${lang === 'en' ? '/en' : ''}`,
-      desc: t('solutionsDesc2'),
-    },
-  ];
-
   return (
     <div>
       <Helmet>
@@ -122,9 +106,9 @@ export default function Home() {
       <HomepageHeader />
       <main className={styles['homepage-main']}>
         <FeatureLayout>
-          <SecondaryTitle>{t('solutions')}</SecondaryTitle>
+          <SecondaryTitle>Features</SecondaryTitle>
           <div className={styles.cardContainer}>
-            {solutions.map(card => (
+            {features.map(card => (
               <ContentCard
                 key={card.id}
                 title={card.title}
@@ -145,19 +129,6 @@ export default function Home() {
           </h1>
         </FeatureLayout>
 
-        <FeatureLayout>
-          <SecondaryTitle>Modern.js Framework</SecondaryTitle>
-          <div className={styles.cardContainer}>
-            {features.map(card => (
-              <ContentCard
-                key={card.id}
-                title={card.title}
-                desc={card.desc}
-                href={card.href}
-              />
-            ))}
-          </div>
-        </FeatureLayout>
         <Footer />
       </main>
     </div>

package/docs/en/guides/topic-detail/generator/_meta.json

@@ -1,17 +0,0 @@
-[
-  {
-    "type": "dir",
-    "name": "create",
-    "label": "@modern-js/create"
-  },
-  {
-    "type": "dir",
-    "name": "new",
-    "label": "new-command"
-  },
-  {
-    "type": "dir",
-    "name": "plugin",
-    "label": "generator-plugin"
-  }
-]

package/docs/en/guides/topic-detail/generator/create/_meta.json

@@ -1 +0,0 @@
-["use", "option", "config"]

package/docs/en/guides/topic-detail/generator/create/config.mdx

@@ -1,59 +0,0 @@
----
-sidebar_position: 3
----
-
-# Configuration Parameters
-
-`@modern-js/create` provides the [--config](/guides/topic-detail/generator/create/option.html#-c,---config-<config>) parameter, which is used to specify the answers to interactive questions in advance during the execution process.
-
-Here, we will introduce the fields and field values that can be configured in the `config` under different scenario.
-
-## General Configuration
-
-### solution
-
-Question: Please select the type of project you want to create.
-
-Options:
-
-- Web App -- mwa
-
-- Npm Module -- module
-
-- Doc Site -- doc
-
-### scenes
-
-Question: Please select the project scenario.
-
-Options:
-
-List of plugin keywords when using custom generator plugins.
-
-## Web App
-
-import LanguageConfig from '@site-docs-en/components/language-config';
-
-<LanguageConfig />
-
-import PackageManager from '@site-docs-en/components/package-manager';
-
-<PackageManager />
-
-## Npm Module
-
-### packageName
-
-Question: Please fill in the project name.
-
-:::info
-The value of the `name` field in the `package.json` file of the Npm module, which is a string type.
-:::
-
-<LanguageConfig />
-
-<PackageManager />
-
-## Modern Doc
-
-<PackageManager />