@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

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

@@ -0,0 +1,423 @@
+---
+title: 路由
+sidebar_position: 1
+---
+# 路由
+
+Modern.js 内置了对 [React Router 6](https://reactrouter.com/en/main) 的**部分**支持，并提供了多种类型的路由模式。根据不同[入口](/guides/concept/entries)类型，将路由分为三种模式，分别是**约定式路由**，**自控式路由**和**其他路由方案**。
+
+:::note
+本小节提到的路由，都是客户端路由，即 SPA 路由。
+
+:::
+
+## 约定式路由
+
+以 `routes/` 为约定的入口，Modern.js 会自动基于文件系统，生成对应的路由结构。
+
+Modern.js 支持了业界流行的约定式路由模式：**嵌套路由**，使用嵌套路由时，页面的路由 与 UI 结构是相呼应的，我们将会详细介绍这种路由模式。
+
+```
+/user/johnny/profile                  /user/johnny/posts
++------------------+                  +-----------------+
+| User             |                  | User            |
+| +--------------+ |                  | +-------------+ |
+| | Profile      | |  +------------>  | | Posts       | |
+| |              | |                  | |             | |
+| +--------------+ |                  | +-------------+ |
++------------------+                  +-----------------+
+```
+
+### 路由文件约定
+
+在`routes/` 目录下，目录名会作为路由 url 的映射，Modern.js 有两个文件约定 `layout.[jt]sx` 和 `page.[jt]sx`（后面简写为 `.tsx`）。这两个文件决定了应用的布局层次，其中 `layout.tsx` 中作为布局组件，`page.tsx` 作为内容组件，是整条路由的叶子节点（一条路由有且仅有一个叶子节点，且必须以叶子节点结尾）。
+
+例如以下目录结构：
+
+```bash
+.
+└── routes
+    ├── page.tsx
+    └── user
+        └── page.tsx
+```
+
+会产出下面两条路由：
+
+- `/`
+- `/user`
+
+当添加 `layout.tsx` 后， 假设有以下目录
+
+:::info
+这里 `routes/layout.tsx` 会作为 `/` 路由下所有组件的布局组件使用， `routes/user/layout.tsx` 会作为 `/user` 路由下所有路由组件的布局组件使用。
+
+:::
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+当路由为 `/` 时，会有以下 UI 布局：
+
+```tsx
+<Layout>
+  <Page />
+</Layout>
+```
+
+同样，`routes/user/layout.tsx` 会作为 `/user` 路由下所有组件的布局组件使用。当路由为 `/user` 时， 会有以下 UI 布局：
+
+```tsx
+<Layout>
+  <UserLayout>
+    <UserPage>
+  <UserLayout>
+</Layout>
+```
+
+#### Layout
+
+`<Layout>` 组件是指 `routes/` 目录下所有 `layout.tsx` 文件，它们表示对应路由片段的布局，使用 `<Outlet>` 表示子组件。
+
+```tsx title=routes/layout.tsx
+import { Link, Outlet, useLoaderData } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <>
+      <Outlet></Outlet>
+    </>
+  );
+};
+```
+
+:::note
+`<Outlet>` 是 React Router 6 中新的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+
+:::
+
+为了方便介绍 `<Layout>` 与 `<Outlet>` 的关系，以下面的文件目录举例：
+
+```bash
+.
+└── routes
+    ├── blog
+    │   └── page.tsx
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+1. 当路由为 `/` 时，`routes/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/page.tsx` 中导出的组件，生成以下 UI 结构：
+
+```tsx
+<Layout>
+  <Page />
+</Layout>
+```
+
+2. 当路由为 `/blog` 时，`routes/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/blog/page.tsx` 中导出的组件，生成以下 UI 结构：
+
+```tsx
+<Layout>
+  <BlogPage />
+</Layout>
+```
+
+3. 当路由为 `/user` 时，`routes/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/user/layout.tsx` 中导出的组件。`routes/user/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/user/page.tsx` 中导出的组件。生成以下 UI 结构：
+
+```tsx
+<Layout>
+  <UserLayout>
+    <UserPage>
+  <UserLayout>
+</Layout>
+```
+
+总结而言，如果子路由的文件目录下存在 `layout.tsx`，上一级 `layout.tsx` 中的 `<Outlet>` 即为子路由文件目录下的 `layout.tsx` ，否则为子路由文件目录下的 `page.tsx`。
+
+#### Page
+
+所有的路由，理论上都应该由 `<Page>` 组件结束。在 `page.tsx` 文件内，如果开发者引入 `<Outlet>` 组件，不会有任何效果。
+
+### 动态路由
+
+通过 `[]` 命名的文件目录，生成的路由会作为动态路由。例如以下文件目录：
+
+```
+└── routes
+    ├── [id]
+    │   └── page.tsx
+    ├── blog
+    │   └── page.tsx
+    └── page.tsx
+```
+
+`routes/[id]/page.tsx` 文件会转为 `/:id` 路由。除了可以确切匹配的 `/blog` 路由，其他所有 `/xxx` 都会匹配到该路由。
+
+在组件中，可以通过 [useParams](/apis/app/runtime/router/#useparams) 获取对应命名的参数。
+
+在 loader 中，params 会作为 [loader](/guides/basic-features/data-fetch#loader-函数) 的入参，通过 `params.xxx` 可以获取。
+
+### 无路径布局
+
+当目录名以 \_\_ 开头时，对应的目录名不会转换为实际的路由路径，例如以下文件目录：
+
+```
+.
+└── routes
+    ├── __auth
+    │   ├── layout.tsx
+    │   ├── login
+    │   │   └── page.tsx
+    │   └── signup
+    │       └── page.tsx
+    ├── layout.tsx
+    └── page.tsx
+```
+
+Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组件会作为 `login/page.tsx` 和 `signup/page.tsx` 的布局组件，但`__auth` 不会作为路由路径片段。
+
+当需要为某些类型的路由，做独立的布局，或是想要将路由做归类时，这一功能非常有用。
+
+### 无布局路径
+
+有些情况下，项目需要较为复杂的路由，但这些路由又不存在独立的 UI 布局，如果像普通文件目录那边创建路由会导致目录层级较深。
+
+因此 Modern.js 支持了通过 `.` 来分割路由片段，代替文件目录。例如，当需要 `/user/profile/2022/edit` 时，可以直接创建如下文件：
+
+```
+└── routes
+    ├── user.profile.[id].edit
+    │      └── page.tsx
+    ├── layout.tsx
+    └── page.tsx
+```
+
+访问路由时，将得到如下 UI 布局：
+
+```tsx
+<RootLayout>
+  <UserProfileEdit /> // routes/user.profile.[id].edit/page.tsx
+</RootLayout>
+```
+
+### (WIP)Loading
+
+`routes/` 下每一层目录中，开发者可以创建 `loading.tsx` 文件，默认导出一个 `<Loading>` 组件。
+
+当路由目录下存在该组件和 `layout` 组件时，这一级子路由下所有的路由切换时，都会以该 `<Loading>` 组件作为 JS Chunk 加载时的 Fallback UI。例如以下文件目录：
+
+```bash
+.
+└── routes
+    ├── blog
+    │   ├── [id]
+    │   │   └── page.tsx
+    │   └── page.tsx
+    ├── layout.tsx
+    ├── loading.tsx
+    └── page.tsx
+```
+
+当定义 `loading.tsx` 时，就相当于以下布局：
+
+```tsx title="当路由为 / 时"
+<Layout>
+  <Suspense fallback={<Loading/>}>
+    <Page><Page>
+  </Suspense>
+</Layout>
+```
+
+```tsx title="当路由为 /blog 时"
+<Layout>
+  <Suspense fallback={<Loading />}>
+    <BlogPage />
+  </Suspense>
+</Layout>
+```
+
+```tsx title="当路由为 /blog/123 时"
+<Layout>
+  <Suspense fallback={<Loading />}>
+    <BlogIdPage />
+  </Suspense>
+</Layout>
+```
+
+:::info
+当目录的 layout 组件不存在时，该目录下的 loading 组件也不会生效。
+Modern.js 建议必须有根 layout 和根 loading。
+
+:::
+
+当路由从 `/` 跳转到 `/blog` 时，如果 `blog/page` 组件的 JS Chunk 还未加载，则会先展示 `loading.tsx` 中导出的组件 UI。
+
+同理，当路由从 `/` 或者 `/blog` 跳转到 `/blog/123` 时，如果 `blog/[id]/page` 组件的 JS Chunk 还未加载，也会先展示 `loading.tsx` 中导出的组件 UI。
+
+### 错误处理
+
+`routes/` 下每一层目录中，开发者同样可以定义一个 `error.tsx` 文件，默认导出一个 `<ErrorBoundary>` 组件。
+
+当有路由目录下存在该组件时，组件渲染出错会被 ErrorBoundary 组件捕获。当目录未定义 `layout.tsx` 文件时，`<ErrorBoundary>` 组件不会生效。
+
+`<ErrorBoundary>` 可以返回出错时的 UI 视图，当前层级未声明 `<ErrorBoundary>` 组件时，错误会向上冒泡到更上层的组件，直到被捕获或抛出错误。同时，当组件出错时，只会影响捕获到该错误的路由组件及子组件，其他组件的状态和视图不受影响，可以继续交互。
+
+{/* Todo API 路由 */}
+
+在 `<ErrorBoundary>` 组件内，可以使用 [useRouteError](/apis/app/runtime/router/#useparams) 获取的错误的具体信息：
+
+```tsx
+import { useRouteError } from '@modern-js/runtime/router';
+const ErrorBoundary = () => {
+  const error = useRouteError();
+  return (
+    <div>
+      <h1>{error.status}</h1>
+      <h2>{error.message}</h2>
+    </div>
+  );
+};
+export default ErrorBoundary;
+```
+
+### 运行时配置
+
+在每个根 `Layout` 组件中(`routes/layout.ts`)，可以动态地定义应用运行时配置：
+
+```ts title="src/routes/layout.tsx"
+// 定义运行时配置
+import type { AppConfig } from '@modern-js/runtime';
+
+export const config = (): AppConfig => {
+  return {
+    router: {
+      supportHtml5History: false
+    }
+  }
+};
+```
+
+### 渲染前的钩子
+
+在有些场景下，需要在应用渲染前做一些操作，可以在 `routes/layout.tsx` 中定义 `init` 钩子，`init` 在客户端和服务端均会执行，基本使用示例如下：
+
+```ts title="src/routes/layout.tsx"
+import type { RuntimeContext } from '@modern-js/runtime';
+
+export const init = (context: RuntimeContext) => {
+  // do something
+};
+```
+
+通过 `init` 钩子可以挂载一些全局的数据，在应用的其他地方可以访问 `runtimeContext` 变量：
+
+:::note
+该功能在应用需要页面前置的数据、自定义数据注入或是框架迁移（如 Next.js）时会非常有用。
+
+:::
+
+```ts title="src/routes/layout.tsx"
+import {
+  RuntimeContext,
+} from '@modern-js/runtime';
+
+export const init = (context: RuntimeContext) => {
+  return {
+    message: 'Hello World',
+  }
+}
+```
+
+```tsx title="src/routes/page.tsx"
+import { useRuntimeContext } from '@modern-js/runtime';
+
+export default () => {
+  const { context } = useRuntimeContext();
+  const { message } = context.getInitData();
+
+  return <div>{message}</div>;
+}
+```
+
+配合 SSR 功能时，浏览器端可以获取到 SSR 时 `init` 返回的数据，开发者可以自行判断是否要在浏览器端重新获取数据来覆盖 SSR 数据，例如：
+
+```tsx title="src/routes/layout.tsx"
+import {
+  RuntimeContext,
+} from '@modern-js/runtime';
+
+export const init = (context: RuntimeContext) => {
+  if (process.env.JUPITER_TARGET === 'node') {
+    return {
+      message: 'Hello World By Server',
+    }
+  } else {
+    const { context } = runtimeContext;
+    const data = context.getInitData();
+    // 如果没有获取到期望的数据
+    if (!data.message) {
+      return {
+        message: 'Hello World By Client'
+      }
+    }
+  }
+}
+```
+
+
+## 自控式路由
+
+以 `src/App.tsx` 为约定的入口，Modern.js 不会多路由做额外的操作，开发者可以自行使用 React Router 6 的 API 进行开发，例如：
+
+```ts title="src/App.tsx"
+import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </BrowserRouter>
+  );
+};
+```
+
+:::note
+Modern.js 默认对约定式路由做了一系列资源加载及渲染上的优化，并且提供了开箱即用的 SSR 能力，而这些能力，在使用自控路由时，都需要开发者自行封装，推荐开发者使用约定式路由。
+
+:::
+
+## 其他路由方案
+
+默认情况下，Modern.js 会开启内置的路由方案，即 React Router。
+
+```js
+export default defineConfig({
+  runtime: {
+    router: true,
+  },
+});
+```
+
+Modern.js 从 `@modern-js/runtime/router` 命名空间暴露了 React Router 的 API 供开发者使用，保证开发者和 Modern.js 中使用同一份代码。另外，这种情况下，React Router 的代码会被打包到 JS 产物中。如果项目已经有自己的路由方案，或者不需要使用客户端路由，可以关闭这个功能。
+
+```js
+export default defineConfig({
+  runtime: {
+    router: false,
+  },
+});
+```

package/zh/guides/concept/entries.mdx

@@ -0,0 +1,210 @@
+---
+title: 入口
+sidebar_position: 2
+---
+# 入口
+
+入口是 Modern.js 默认的文件约定，项目的每一个入口是一张独立的页面，对应一条**服务端路由**。
+
+很多配置，如 HTML 模板、Meta 信息、是否开启 SSR、SSG、服务端路由规则都是以入口为维度划分的。
+
+## 单入口与多入口
+
+Modern.js 初始化的项目是单入口的，项目结构如下：
+
+```
+.
+├── src
+│   ├── modern-app-env.d.ts
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+├── package.json
+├── modern.config.ts
+├── pnpm-lock.yaml
+├── README.md
+└── tsconfig.json
+```
+
+Modern.js 可以很方便的将单入口切换成多入口。可以在项目下执行 `pnpm run new`，通过生成器创建入口：
+
+```bash
+? 请选择你想要的操作 创建工程元素
+? 创建工程元素 新建「应用入口」
+? 请填写入口名称 new-entry
+```
+
+执行后，`src/` 目录将会变成如下结构：
+
+```
+.
+├── modern-app-env.d.ts
+├── myapp
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+└── new-entry
+    └── routes
+        ├── index.css
+        ├── layout.tsx
+        └── page.tsx
+```
+
+原本的代码被移动到了和 `package.json` 中 `name` 同名的目录下，并创建了新的目录。
+
+执行 `pnpm run dev` 后，可以看到新增一条 `/new-entry` 的路由，并且被迁移的代码路由并未发生变化。
+
+:::note
+Modern.js 会将和 `package.json` 中 `name` 字段同名的入口作为主入口，默认路由为 `/`，其他入口默认路由为 `/{entryName}`。
+
+:::
+
+## 入口类型
+
+不同的入口类型具有不同的编译和运行时行为。在 Modern.js 创建项目时，开发者可以手动选择创建**框架模式**或是**构建模式**的项目。完成创建后，可以看到不同模式的项目样板文件是不同的。
+
+默认情况下，Modern.js 启动项目前会对 `src/` 下的文件进行扫描，识别入口，并生成对应的服务端路由。
+
+:::tip
+可以通过 [source.entriesDir](/configure/app/source/entries-dir) 更改入口目录为其他目录。
+
+:::
+
+并非 `src/` 下所有的一级目录都会成为项目入口, 入口所在目录必须满足以下四个条件之一：
+
+1. 具有 `routes/` 目录
+2. 具有 `App.[jt]sx?` 文件
+3. 具有 `index.[jt]sx?` 文件
+4. 具有 `pages/` 目录（兼容 Modern.js 1.0）
+
+当 `src/` 目录满足入口特征时，Modern.js 会认为当前项目为单入口应用。
+
+:::tip
+单入口默认的入口名为 `main`。
+
+:::
+
+当项目不是单入口应用时，Modern.js 会进一步查看 `src/` 下的一级目录。
+
+### 框架模式入口
+
+框架模式指需要使用 Modern.js 框架能力，例如 Router、SSR、一体化调用等。这类入口约定下，开发者定义的入口并不是真正的 Webpack 编译入口。Modern.js 在启动时会生成一个封装过的入口，可以在 `node_modules/.modern/{entryName}/index.js` 找到真正的入口。
+
+#### 约定式路由
+
+如果入口中存在 `routes/` 目录，Modern.js 会在启动时扫描 `routes/` 下的文件，基于文件约定，自动生成客户端路由（react-router）。
+
+详细内容可以参考[路由](/guides/basic-features/routes)。
+
+#### 自定义路由
+
+如果入口中存在 `App.[jt]sx?` 文件，开发者可以在这个文件中自由的设置客户端路由，或者不设置客户端路由。
+
+详细内容可以参考[路由](/guides/basic-features/routes)。
+
+#### 自定义 App
+
+如果入口中存在 `index.[jt]sx` 文件，并且当文件默认导出函数时，Modern.js 还是会根据 runtime 的设置情况生成 createApp 包裹后的代码。在渲染过程中，将 createApp 包裹后的组件作为参数传递给 index 文件导出的函数，这样开发者可以自定义将组件挂载到 DOM 节点上，或在挂载前添加自定义行为。例如：
+
+```tsx
+import ReactDOM from 'react-dom/client';
+import { bootstrap } from '@modern-js/runtime';
+
+export default (App: React.ComponentType) => {
+  // do something before bootstrap...
+  bootstrap(App, 'root', undefined, ReactDOM);
+};
+```
+
+:::warning
+由于 bootstrap 函数需要兼容 React17 和 React18 的用法，调用 bootstrap 函数时需要手动传入 ReactDOM 参数。
+
+:::
+
+Modern.js 生成的文件内容如下：
+
+```js
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import customBootstrap from '@_edenx_src/index.tsx';
+import App from '@_edenx_src/App';
+import { router, state } from '@edenx/runtime/plugins';
+
+const IS_BROWSER = typeof window !== 'undefined' && window.name !== 'nodejs';
+const MOUNT_ID = 'root';
+
+let AppWrapper = null;
+
+function render() {
+  AppWrapper = createApp({
+    // runtime 的插件参数...
+  })(App);
+  if (IS_BROWSER) {
+    customBootstrap(AppWrapper);
+  }
+  return AppWrapper;
+}
+
+AppWrapper = render();
+
+export default AppWrapper;
+```
+
+### 构建模式入口
+
+构建模式是指不使用任何 Modern.js 运行时的能力，完全由开发者自己定义项目 Webpack 的入口。
+
+如果入口中存在 `index.[jt]sx` ，并且没有默认导出函数时，这时候该文件就是真正的 Webpack 入口文件。这里和 [Create React App](https://github.com/facebook/create-react-app) 类似，需要自己将组件挂载到 DOM 节点、添加热更新代码等。例如:
+
+```js title=src/index.jsx
+import React from 'react';
+import ReactDOM from 'react-dom';
+import App from './App';
+
+ReactDOM.render(<App />, document.getElementById('root'));
+```
+
+Modern.js **不推荐**使用这种方式，这种方式丧失了框架的一些能力，如 **`modern.config.js` 文件中的 `runtime` 配置将不会再生效**。但是在项目从其他框架迁移到 Modern.js，例如 CRA，或是自己手动搭建的 webpack 时，这种方式会非常有用。
+
+## 使用配置文件定义入口
+
+有些时候，已有的项目并不是按照 Modern.js 的目录结构来搭建的。如果强行要按照这种结构来工作，会有比较大的迁移成本。
+
+在 Modern.js 中，除了使用文件约定生成入口外，还可以在 `modern.config.[jt]s` 中手动配置入口。
+
+```ts
+export default defineConfig({
+  source: {
+    entries: {
+      // 指定一个名称为 entry_customize 的新入口
+      entry_customize: './src/home/test/index.js',
+    },
+  },
+});
+```
+
+:::tip
+详情可以查看 [source.entries](/configure/app/source/entries)。
+
+:::
+
+## 禁用默认入口扫描
+
+另外，项目的部分结构可能恰巧命中了 Modern.js 的约定，但实际上这部分并不是真实的入口。
+
+Modern.js 提供了配置，来禁用默认的入口扫描。与配置的入口结合使用，大部分项目可以在不修改目录结构的情况下，快速的进行迁移。
+
+```ts
+export default defineConfig({
+  source: {
+    disableDefaultEntries: true,
+  },
+});
+```
+
+:::tip
+详情可以查看 [source.disableDefaultEntries](/configure/app/source/disable-default-entries)。
+
+:::