@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/apis/app/hooks/src/pages.md

@@ -0,0 +1,183 @@
+---
+title: src/pages/, src/[entry]/pages/
+sidebar_position: 2
+---
+
+应用项目基于文件系统路由的入口标识。
+
+当项目结构为 `Pages 入口` 类型时， 会分析 `src/pages` 目录下的文件得到客户端路由配置。
+
+
+举例说明，例如以下目录结构：
+
+```bash
+.
+└── src
+    └── pages
+        ├── about
+        │   └── index.jsx
+        ├── index.jsx
+        └── info.jsx
+```
+
+对应生成的路由配置为:
+
+```bash
+[
+  { path: '/', component: 'pages/index.jsx' },
+  { path: '/info' component: 'pages/info.jsx' },
+  { path: '/about', component: 'pages/about/index.jsx' }
+]
+```
+
+pages 目录下的文件满足以下条件的不会被当做路由文件
+
+- 后缀不是 `.(j|t)sx?` 的文件。
+- `.d.ts` 类型定义文件。
+- 以 `.(test|spec|e2e).(j|t)sx?` 结尾的测试文件。
+
+:::tip 提示
+
+推荐 pages 目录下只写入口代码，把业务逻辑写到 pages 外面独立的 features 目录里。这样 pages 目录下大部分文件都会是路由文件，也就不需要额外的过滤规则。
+
+:::
+
+### 动态路由
+
+使用 `[ ]` 包裹的目录或文件会被视为动态路由
+
+例如以下目录结构:
+
+```bash
+.
+└── src
+    └── pages
+        ├── [post]
+        │   ├── detail.jsx
+        │   └── index.js
+        ├── users
+        │   └── [id].jsx
+        ├── index.jsx
+        └── info.jsx
+```
+
+对应生成的路由配置为:
+
+```js
+[
+  { path: '/', component: 'pages/index.jsx' },
+  { path: '/info', component: 'pages/info.jsx' },
+  { path: '/:post/', component: 'pages/[post]/index.js' },
+  { path: '/:post/detail' components: 'pages/[post]/detail.jsx'},
+  { path: '/users/:id', components: 'pages/users/[id].jsx'}
+]
+```
+
+动态路由的基础上，支持添加特殊的路由后缀 `(*、?、+)`。
+
+例如：`src/pages/users/[id]*.tsx` 最终路由为 `/users/:id*`
+
+### 全局 layout
+
+整个应用需要全局的 `layout` 时， 可以通过 `pages/_app.tsx` 实现，具体写法如下:
+
+```js
+import React from 'react';
+import UserLayout from 'xxxx';
+
+export default const App = ({Component, ...pageProps}:{ Component: React.ComponentType}) => {
+  return (
+    <UserLayout>
+      <Component {...pageProps} />
+    </UserLayout>
+  );
+}
+```
+
+上述 `App` 为访问具体路由匹配到的组件。
+
+例如以下目录结构:
+
+```bash
+.
+└── pages
+    ├── a
+    │   ├── b
+    │   │   └── index.js
+    │   └── index.js
+    └── index.js
+```
+
+- 访问 `/` 时，对应的 `Component` 组件为 `pages/index.js`。
+- 访问 `/a` 时，对应的 `Component` 组件为 `pages/a/index.js`。
+- 访问 `/a/b` 时，对应的 `Component` 组件为 `pages/a/b/index.js`。
+
+:::tip 全局 layout 有以下优点
+
+- 页面变化时，保留全局布局的状态
+- 添加全局样式
+- ComponentDidCatch 错误处理
+- 使用 `defineConfig`(/docs/apis/app/runtime/app/define-config) 动态配置运行时配置。
+
+:::
+
+### 部分 layout
+
+开发应用时，存在同一路由下的子路由共用 layout 的场景。
+
+针对这一场景，Modern.js 约定，当目录下存在 `_layout.js` ，就会有类似全局 layout 的效果。
+
+例如以下目录结构:
+
+```bash
+└── pages
+    ├── a
+    │   ├── b
+    │   │   └── index.js
+    │   ├── _layout.js
+    │   └── index.js
+    └── index.js
+```
+
+```js title="pages/a/_layout.js"
+import React from 'react';
+
+const ALayout = ({ Component, ...pageProps }) => {
+  return <Component {...pageProps} />;
+};
+export default ALayout;
+```
+
+Component 参数为访问具体路由对应的组件，例如
+
+- 访问 `/a` 时，对应的 `Component` 组件为 `pages/a/index.js`。
+- 访问 `/a/b` 时，对应的 `Component` 组件为 `pages/a/b/index.js`。
+
+这样就可以用 `pages/a/_layout.js` 满足 `a` 目录下路由共用 layout 的需求。
+
+### 404 路由
+
+约定 `pages/404.[tj]sx` 为默认的 404 路由。
+
+例如以下目录结构:
+
+```bash
+.
+└── src
+    └── pages
+        ├── user.js
+        ├── home.js
+        ├── 404.js
+```
+
+生成路由配置如下:
+
+```bash
+[
+ { path: '/user', component: './pages/user.js'},
+ { path: '/home', component: './pages/home.js' },
+ { path: '*', component: './pages/404.js'}
+]
+```
+
+所有未匹配的路由，都将匹配到 `pages/404.[tj]s`。

package/zh/apis/app/hooks/src/stories.md

@@ -0,0 +1,14 @@
+---
+title: "src/**/*.stories.[tj]sx"
+sidebar_position: 7
+---
+
+应用项目 Storybook 调试文件。
+
+可以在项目源码目录(src)下创建 `*.stories.[tj]sx` 格式的文件作为 Storybook 的调试文件。
+
+在项目下执行 dev story 命令，支持使用这些文件在 Storybook 中对相关内容进行调试。
+
+:::info 注
+使用 Storybook 需要提前在项目下执行 new 命令启用「Visual Testing (Storybook)」模式。
+:::

package/zh/apis/app/hooks/src/test.md

@@ -0,0 +1,12 @@
+---
+title: "src/**/*.test.[tj]sx?"
+sidebar_position: 6
+---
+
+应用项目测试文件。
+
+应用项目支持在项目源码目录(src)下创建后缀为 `.test.[tj]sx?` 文件进行编写测试用例。
+
+:::info 注
+使用单元测试、集成测试需要提前在项目下执行 new 命令启用「单元测试 / 集成测试」功能。
+:::

package/zh/apis/app/overview.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 0
+---
+
+# 概览
+本节涵盖了使用@modern-js/app-tools的所有API。
+
+import OverviewNav from '@site/src/components/OverviewNav';
+import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json';
+
+<OverviewNav cards={sidebarData.docsSidebars.apisAppSidebar} />

package/zh/apis/app/runtime/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "运行时",
+  "position": 3,
+  "collapsed": false,
+  "link": {
+    "type": "doc",
+    "id": "apis/app/runtime/index"
+  }
+}

package/zh/apis/app/runtime/app/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "App API",
+  "position": 3
+}

package/zh/apis/app/runtime/app/bootstrap.md

@@ -0,0 +1,83 @@
+---
+title: bootstrap
+sidebar_position: 8
+---
+
+:::info 补充信息
+用于启动并加载应用。
+```ts
+import { bootstrap } from '@modern-js/runtime';
+```
+:::
+
+:::tip 提示
+- 只有自定义入口，即使用 `index.tsx` 而非 `App.tsx` 时，才需要使用该 API。
+- 需要结合 [`createApp`](./create-app.md) 使用。
+:::
+
+## API
+
+`bootstrap(AppComponent, rootElement) => React.ComponentType<any> | void`
+
+### 参数
+
+- AppComponent：`React.ComponentType<any>`，应用根组件，通过 [`createApp`](./create-app.md) 创建。
+- rootElement：`string`，要挂载的 DOM 根元素 id，如 `"root"`。
+
+## 示例
+
+### 非 `SSR` 页面使用
+
+```tsx
+import { createApp, bootstrap } from '@modern-js/runtime';
+import { router, state } from '@modern-js/runtime/plugins';
+import { effects, autoActions } from '@modern-js/runtime/model';
+
+function App() {
+  return <div>Hello Modern.js</div>
+}
+
+const WrappedApp = createApp({
+  // 传入自定义插件
+  plugins: [
+    router({}),
+    state({
+      plugins: [autoActions(), effects()]
+    })
+  ]
+})(App);
+
+bootstrap(WrappedApp, 'root'));
+```
+
+### `SSR` 页面使用
+
+对于 `SSR` 页面，因为组件代码在浏览器端和服务端都会执行，需要通过 `typeof window !== 'undefined'` 区分环境，并暴露 `serverRender` 供服务端渲染。
+
+```tsx
+import { createApp, bootstrap } from '@modern-js/runtime';
+import { router, state } from '@modern-js/runtime/plugins';
+import { effects, autoActions } from '@modern-js/runtime/model';
+
+function App() {
+  return <div>Hello Modern.js</div>
+}
+
+const WrappedApp = createApp({
+  // 传入自定义插件
+  plugins: [
+    router({}),
+    state({
+      plugins: [autoActions(), effects()]
+    })
+  ]
+})(App);
+
+if (typeof window !== 'undefined') {
+  bootstrap(WrappedApp, 'root');
+}
+
+export function serverRender(context: any) {
+  return bootstrap(WrappedApp, context)
+}
+```

package/zh/apis/app/runtime/app/create-app.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 10
+---
+
+# createApp
+
+:::info 补充信息
+用于创建自定义入口，定制插件。
+```ts
+import { createApp } from '@modern-js/runtime';
+```
+:::
+
+## API
+
+`createApp(options) => React.ComponentType<any>`
+
+### 参数
+
+- options：`object`，可选的参数。
+  - [plugins]：`Plugin[]`，自定义的插件扩展。
+
+## 示例
+
+### 创建自定义入口
+
+详见 [`bootstrap`](./bootstrap.md)。
+
+### 定制插件
+
+```ts
+import { createApp } from '@modern-js/runtime';
+
+function App() {
+  return <div>app</div>;
+}
+
+export default createApp({
+  plugins: [
+    router({}),
+    state({
+      plugins: [autoActions(), effects()]
+    })
+  ]
+})(App)
+
+```

package/zh/apis/app/runtime/app/define-config.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 12
+title: defineConfig
+---
+
+:::info 补充信息
+用于动态配置应用。
+```ts
+import { defineConfig } from '@modern-js/runtime';
+```
+:::
+
+Runtime 配置通常可以在 `modern.config.js` 的 `runtime` 空间下配置，如 [runtime.router](/docs/configure/app/runtime/router) 等。
+但如果一些配置参数是运行时获取的，或者配置参数是来自于源码中的一个模块（如组件），开发者就可以在 `modern.config.js` 使用 `defineConfig` API 进行运行时的配置。
+
+:::info
+`@modern-js/app-tools` 拥有同名 API ，用于**编译时配置定义**，请开发者加以区分。
+:::
+
+## API
+
+`defineConfig(Component, config): any`
+
+### 参数
+
+- Component：`React.ComponentType<any>`，App 根组件。
+- config：`Record<string, any>`，运行时的配置。
+
+## 示例
+
+```tsx
+function App () {
+  ...
+}
+
+defineConfig(App, {
+  router: {
+    supportHtml5History: false
+  }
+})
+```
+
+
+1. `defineConfig` 里可配置 [runtime.state](/docs/configure/app/runtime/state)、[runtime.router](/docs/configure/app/runtime/router) 等运行时配置。字段和 `modern.config.js` 下的 `runtime` 配置字段一致。
+
+2. `defineConfig` 在配置某个属性之前，如 `router`，需要确保 `modern.config.js` 已经配置开启了该功能。
+
+3. `defineConfig` 传入的配置会和 `modern.config.js` 重的配置浅 merge，以 `router` 为例，最终应用的配置如下。
+
+```json
+{
+  // 来自 `modern.config.js` 配置
+  ...runtime.router
+  // 来自 `defineConfig` 配置
+  ...config.router
+}
+```

package/zh/apis/app/runtime/app/head.md

@@ -0,0 +1,43 @@
+---
+title: Head
+sidebar_position: 1
+---
+
+# Head
+
+:::info 补充信息
+用于给 `head` 元素内添加 html 元素（如 title、meta、script 等），并且支持 `SSR`。
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+```
+:::
+
+## API
+
+```tsx
+<Helmet></Helmet>
+```
+
+## 示例
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+
+function IndexPage() {
+  return (
+    <div>
+      <Helmet>
+        <title>My page title</title>
+        <meta name="viewport" content="initial-scale=1.0, width=device-width" />
+      </Helmet>
+      <p>Hello Modern.js!</p>
+    </div>
+  )
+}
+
+export default IndexPage
+```
+
+## 更多用法
+
+详见 [react-helmet](https://github.com/nfl/react-helmet)。

package/zh/apis/app/runtime/app/no-ssr.md

@@ -0,0 +1,41 @@
+---
+title: NoSSR
+sidebar_position: 4
+---
+
+:::info 补充信息
+被 NoSSR 包裹的内容在服务端不会进行渲染，在客户端 hydrate 阶段也不会渲染，等到整个 App mount 后便会立即渲染。
+```ts
+import { NoSSR } from '@modern-js/runtime/ssr';
+```
+:::
+
+## API
+
+```tsx
+<NoSSR></NoSSR>
+```
+
+## 示例
+
+下列代码中，`Time` 组件用于展示当前的时间，由于服务端渲染和客户端 hydrate 时获取到的时间是不一致的，react 就会抛出异常。针对这种情况可以使用 `NoSSR` 进行优化：
+
+```tsx
+import { NoSSR } from '@modern-js/runtime/ssr';
+
+function Time() {
+  return <NoSSR>
+    <div>Time: { Date.now() }</div>
+  </NoSSR>
+}
+```
+
+## 使用场景
+
+在 CSR 中，常常需要根据当前浏览器 UA，或是当前页面 URL 的某个参数的不同，来渲染不同的内容。
+
+如果此时应用直接切换到 SSR，很有可能出现不符合预期的结果。
+
+Modern.js 在 SSR 上下文中提供了完整的浏览器端信息，合理利用上下文信息来决定组件在服务端的渲染结果，避免出现 Jarring Render。
+
+如果应用里有太多的判断，希望以后再使用上下文；或者不希望某些内容在服务端被渲染，可以使用 NoSSR 组件将这一部分剔除在服务端渲染外。

package/zh/apis/app/runtime/app/pre-render.md

@@ -0,0 +1,77 @@
+---
+title: PreRender
+sidebar_position: 5
+---
+
+:::info 补充信息
+无展示内容的高阶组件，通过类似 Helmet 的方式实现 SPA 路由级的缓存，无需额外配置。
+```ts
+import { PreRender } from '@modern-js/runtime/ssr';
+```
+:::
+
+## API
+
+`PreRender` 组件提供了一套常用的配置参数，用于控制缓存的规则、过期时间、缓存算法等。
+
+```tsx
+<PreRender></PreRender>
+```
+
+### 参数
+
+- interval：`number`，设置缓存保持新鲜的时间，单位秒。在该时间内，将直接使用缓存，并且不做异步渲染。
+- [staleLimit]：`number`，设置缓存完全过期的时间，单位秒。在该时间内，缓存可以被返回，否则必须使用重新渲染的结果。
+- [level]：`number`，设置缓存标识的计算规则等级，通常配合 `includes` 与 `matches` 使用。默认值为 `0`。
+
+```bash
+0：路由路径
+1：路由路径 + 查询字符串
+2：路由路径 + 请求头
+3：路由路径 + 查询字符串 + 请求头
+```
+
+- [includes]：`{ header?: string[], query?: string[] }`，设置需要被纳入缓存标识的内容，在 level 非 0 时使用。默认值为 `null`。
+- [matches]：`{ header?: Record<string, any>, query?: Record<string, any> }`，设置 query 或 header 的值在缓存标识计算中的重写规则，通常用在缓存分类时，支持正则表达式。默认值为 `null`。
+
+## 示例
+
+```tsx
+import { PreRender } from '@modern-js/runtime/ssr';
+
+export default function App() {
+  return (
+    <>
+        <PreRender interval={10} />
+        <div>Hello Modern</div>
+    </>
+  )
+}
+```
+
+下面例子展示了如何将 query、header 中指定的参数纳入缓存计算中：
+
+```tsx
+/* 使用 query 中的 channel 和 header 中的 language 计算缓存标识 */
+<PreRender interval={10} level={2} includes={{
+    query: ["channel"],
+    header: ["language"]
+}} />
+```
+
+下面例子展示了如何不让测试频道影响线上缓存：
+
+```tsx
+/* 将 query 中 channel 值为 test_ 开头的重写为 testChannel，否则重写为 otherChannel */
+<PreRender interval={10} level={2} includes={{
+    query: ["channel"],
+    header: ["language"]
+}} matches={{
+    query: {
+        channel: {
+            "testChannel", "^test_",
+            "otherChannel", ".*"
+        }
+    }
+}} />
+```

package/zh/apis/app/runtime/app/use-module-app.md

@@ -0,0 +1,60 @@
+---
+title: useModuleApp
+sidebar_position: 6
+---
+
+:::info 补充信息
+返回一个自动切换微前端路由的组件，默认激活的路由是配置里的 `activeWhen`。
+```ts
+import { useModuleApp } from '@modern-js/runtime';
+```
+:::
+
+:::caution 注意
+该 API 在微前端主应用中使用，需要先开启微前端。
+:::
+
+## API
+
+`useModuleApp() => React.FC<any>`
+
+返回子应用的 React 组件。
+
+## 示例
+
+需要先配置微前端子应用信息。
+
+```js title=modern.config.js
+defineConfig({
+  runtime: {
+    masterApp: {
+      manifest: {
+        modules: [
+          {
+            name: 'Home',
+            entry: 'http://www.home.com',
+            activeWhen: '/home'
+          },
+          {
+            name: 'Contact',
+            entry: 'http://www.contact.com',
+            activeWhen: '/contact'
+          },
+        ]
+      }
+    }
+  }
+})
+```
+
+```ts title=App.tsx
+import { useModuleApp } from '@modern-js/runtime';
+
+function App() {
+  const MApp = useModuleApp();
+
+  return <MApp />;
+}
+```
+
+通过 `useModuleApp()` 获取到 `MApp` 组件，渲染 MApp 组件，将会根据配置中的 `activeWhen` 作为激活路由加载对应的子应用。