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

package/docs/en/tutorials/first-app/c08-entries.mdx

@@ -1,135 +0,0 @@
----
-title: Add Application Entry
----
-# Add Application Entry
-
-In the last chapter, we basically completed the development of the point of contact list application, introduced the usage of some functions in the Modern.js, and recommended best practices.
-
-In this chapter, we will describe how to add a new entry to the application.
-
-## New entry
-
-A complete project may require multiple entries, Modern.js supports the automatic creation of new entries, as mentioned in the previous section, `pnpm run new` can enable optional features.
-
-We can also use it to create new project elements and execute `pnpm run new` in the project root directory:
-
-```bash
-? Please select the operation you want: Create Element
-? Please select the type of element to create: New "entry"
-? Please fill in the entry name: landing-page
-```
-
-When created, the project will look like this:
-
-```bash
-.
-├── README.md
-├── modern.config.ts
-├── node_modules
-├── package.json
-├── pnpm-lock.yaml
-├── src
-│   ├── modern-app-env.d.ts
-│   ├── landing-page
-│   │   └── routes
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       └── page.tsx
-│   └── myapp
-│       ├── components
-│       │   ├── Avatar
-│       │   │   └── index.tsx
-│       │   └── Item
-│       │       └── index.tsx
-│       ├── containers
-│       │   └── Contacts.tsx
-│       ├── models
-│       │   └── contacts.ts
-│       ├── routes
-│       │   ├── archives
-│       │   │   └── page.tsx
-│       │   ├── layout.tsx
-│       │   └── page.tsx
-│       └── styles
-│           └── utils.css
-└── tsconfig.json
-```
-
-You can see that the files of the contact list application are automatically refactored into `src/myapp/`.
-
-At the same time, a new `src/landing-page/` is created, which also has `routes/*` (the `pnpm run new` command only does these things, so you can also easily create new entries or modify entries manually).
-
-Execute `pnpm run dev` to display:
-
-![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c08-entries-myapp.png)
-
-Access `http://localhost:8080/` to see the application as before.
-
-Visit `http://localhost:8080/landing-page` to see the landing-page for the new entry you just created (Modern.js automatically generated default page).
-
-One of the design principles of the Modern.js framework is [[Convention over Configuration](https://en.wikipedia.org/wiki/Convention_over_configuration) ]. In most cases, you can write code directly by convention without any configuration. The directory structure in `src/` is a convention:
-
-`src/myapp/` and `src/landing-page/` are automatically identified as two application portals: myapp and landing-page.
-
-The directory name of `src/myapp/` is the same as the project name (`name` in `package.json`), which will be considered as the main entry of the project, and the root path of the project URL (the default in the development environment is `http://localhost:8080/`) will automatically point to the main entry.
-
-The URL of other entries is to append the entry name after the root path, such as `http://localhost:8080/landing-page`.
-
-Next, we rename `src/myapp/` to `src/contacts/`:
-
-```bash
-mv src/myapp src/contacts
-```
-
-Execute `pnpm run dev` again, the result becomes:
-
-![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c08-entries-contacts.png)
-
-There is no longer a main entry, the point of contact list is now a normal entry that needs to be accessed with `http://localhost:8080/contacts`.
-
-## Modify the configuration by entry
-
-In the Modern.js configuration file, we can write our own code to control the configuration of the project.
-
-Now, modify the `modern.config.ts` to add something:
-
-```ts title="modern.config.ts"
-import { appTools, defineConfig } from '@modern-js/app-tools';
-import { tailwindcssPlugin } from '@modern-js/plugin-tailwindcss';
-
-export default defineConfig({
-  runtime: {
-    router: true,
-    state: true,
-  },
-  server: {
-    ssr: true,
-    ssrByEntries: {
-      'landing-page': false,
-    },
-  },
-  plugins: [appTools(), tailwindcssPlugin()],
-});
-```
-
-Execute `pnpm run dev`, and then open `view-source: http://localhost:8080/landing-page` with the browser, you can see that the content of the `landing-page` web page is dynamically loaded through js, and the SSR function of this page is turned off.
-
-If `ssrByEntries` and its value are annotated, the SSR function of landing-page is restored.
-
-Other times, you need some more sophisticated logic to do the setup, such as JS variables, expressions, import modules, etc., for example, only in the development environment to enable SSR:
-
-```js
-export default defineConfig({
-  server: {
-    ssrByEntries: {
-      'landing-page': process.env.NODE_ENV !== 'production',
-    },
-  },
-});
-```
-
-So far, the prototype of our point of contact list application is almost complete 👏👏👏.
-
-## Next step
-
-Then you can further refine your application by following more tutorials like [Guides](/guides/get-started/quick-start), [configuration](/configure/app/usage), and more.

package/docs/zh/apis/app/hooks/server/index_.mdx

@@ -1,10 +0,0 @@
----
-title: index.[tj]s
-sidebar_position: 1
----
-
-# index.[tj]s
-
-扩展 Modern.js Web Server 的文件，在此文件中可以给 Modern.js 工程启动的 Web Server 添加 [Hook](/apis/app/runtime/web-server/hook) 或 [Middleware](/apis/app/runtime/web-server/middleware)。
-
-可以对请求和响应进行拦截处理，鉴权与角色、请求预处理、异常兜底等。也可在内置处理逻辑（包括路由匹配、资源寻址、头部注入、页面渲染，静态 Web 托管）插入特定的业务逻辑。

package/docs/zh/apis/app/hooks/src/index_.mdx

@@ -1,39 +0,0 @@
----
-title: index.[tj]s
-sidebar_position: 4
----
-# index.[tj]s
-
-:::warning
-即将废弃，推荐使用 [`entry.[tj]s`](/apis/app/hooks/src/entry)。
-:::
-
-应用使用自定义 `bootstrap` 时的入口标识。
-
-通常情况下 [`App.[tj]sx`](/apis/app/hooks/src/app) 钩子文件已经能满足我们的需求，当我们需要在 `bootstrap` 之前添加自定义行为或者完全接管 webpack 打包入口时，可以在 `src` 或者入口目录下放置 `index.[tj]s`。 下面有分两种情况进行讨论：
-
-## 在 bootstrap 之前添加自定义行为
-
-只需要 `src/index.[tj]s` 默认导出函数：
-
-```js title=src/index.js
-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);
-};
-```
-
-## 完全接管 webpack 入口
-
-当 `src/index.[tj]sx?` 下没有默认导出函数时，该文件即为真正的 webpack 打包入口文件, 可以直接像使用 create-react-app 等脚手架一样组织代码：
-
-```js title=src/index.jsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import App from './App';
-
-ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
-```

package/docs/zh/apis/app/hooks/src/stories.mdx

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

package/docs/zh/apis/app/runtime/app/define-config.mdx

@@ -1,67 +0,0 @@
----
-sidebar_position: 1
-title: defineConfig
----
-# defineConfig
-
-:::warning
-
-该 API 即将废弃，推荐使用 `src/modern.runtime.ts` 定义 Runtime 配置，同时支持静态配置和动态配置，使用姿势请参考 [Runtime 配置](/configure/app/runtime/0-intro.html)
-:::
-
-用于动态配置应用。
-
-## 使用姿势
-
-```ts
-import { defineConfig } from '@modern-js/runtime';
-```
-
-Runtime 配置通常可以在 `modern.config.js` 的 `runtime` 空间下配置，如 [router](/configure/app/runtime/router) 配置。
-
-`modern.config.js` 中的配置是构建时确定的，如果一些配置参数是运行时获取的，或者配置参数是来自于源码中的一个模块（如组件），就需要使用 `defineConfig` API 进行运行时配置。
-
-:::info
-`@modern-js/app-tools` 拥有同名 API，用于为配置**提供 TS 类型**，请开发者加以区分。
-
-:::
-
-## 函数签名
-
-```ts
-function 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](/configure/app/runtime/state)、[runtime.router](/configure/app/runtime/router) 等运行时配置。
-
-2. `defineConfig` 在配置某个属性之前，如 `router`，需要确保 `modern.config.js` 已经配置开启了该功能。
-
-3. `defineConfig` 传入的配置会和 `modern.config.js` 中的配置浅 merge，以 `router` 为例，最终应用的配置如下：
-
-```json
-{
-  // 来自 `modern.config.js` 配置
-  ...runtime.router
-  // 来自 `defineConfig` 配置
-  ...config.router
-}
-```

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

@@ -1,74 +0,0 @@
----
-title: bootstrap
----
-# bootstrap
-
-:::warning
-即将废弃，推荐使用 [`render`](/apis/app/runtime/core/render)。
-:::
-
-用于启动和挂载应用，通常情况下不做手动调用。只有在使用[自定义 Bootstrap](/guides/concept/entries#自定义-bootstrap) 时，才需要使用该 API。
-
-## 使用姿势
-
-```ts
-import ReactDOM from 'react-dom/client';
-import { bootstrap } from '@modern-js/runtime';
-
-bootstrap(App, 'root', undefined, ReactDOM);
-```
-
-## 函数签名
-
-```ts
-type BootStrap<T = unknown> = (
-  App: React.ComponentType,
-  id: string | HTMLElement | RuntimeContext,
-  root?: any,
-  ReactDOM?: {
-    render?: Renderer;
-    hydrate?: Renderer;
-    createRoot?: typeof createRoot;
-    hydrateRoot?: typeof hydrateRoot;
-  },
-) => Promise<T>;
-```
-
-### 参数
-
-- `AppComponent`：通过 [`createApp`](./create-app) 创建的 ReactElement 实例。
-- `id`：要挂载的 DOM 根元素 id，如 `"root"`。
-- `root`: ReactDOM.createRoot 的返回值，用于 bootstrap 函数外需要 root 销毁组件的场景。
-- `ReactDOM`: ReactDOM 对象，用于区分 React 18 和 React 17 API。
-
-## 示例
-
-```tsx
-import ReactDOM from 'react-dom/client';
-import { createApp, bootstrap } from '@modern-js/runtime';
-
-function App() {
-  return <div>Hello Modern.js</div>;
-}
-
-const WrappedApp = createApp({
-  // 传入自定义插件
-  plugins: [customPlugin()],
-})(App);
-
-bootstrap(WrappedApp, 'root', undefined, ReactDOM);
-```
-
-:::info
-由于 `@modern-js/runtime/plugins` 是别名处理的，在 ts 项目中使用时需要声明其类型， 只需要在 `src/modern-app-env.d.ts` 添加以下类型声明即可：
-
-```ts
-declare module '@modern-js/runtime/plugins';
-```
-
-:::
-
-:::warning
-bootstrap 只支持在 CSR 场景下使用。
-
-:::

package/docs/zh/apis/app/runtime/core/create-app.mdx

@@ -1,35 +0,0 @@
----
-title: createApp
----
-# createApp
-
-:::warning
-即将废弃，推荐使用 [`createRoot`](/apis/app/runtime/core/create-root)。
-:::
-
-用于创建自定义入口，定制运行时插件。
-
-## 使用姿势
-
-```ts
-import { createApp } from '@modern-js/runtime';
-```
-
-## 函数签名
-
-```ts
-import type { Plugin } from '@modern-js/runtime';
-
-function createApp(options: { plugins: Plugin[] }): React.ComponentType<any>;
-```
-
-### 参数
-
-- `options`: 可选的参数。
-  - `plugins`：自定义的插件扩展。
-
-## 示例
-
-### 创建自定义入口
-
-详见 [`bootstrap`](./bootstrap.mdx)。

package/docs/zh/apis/app/runtime/core/use-loader.mdx

@@ -1,89 +0,0 @@
----
-title: useLoader
----
-# useLoader
-
-一个同构的 API，通常会用来做异步请求。当 SSR 的时候，服务端使用 `useLoader` 预加载数据，同时浏览器端也会复用这部分数据。
-
-:::tip
-在使用 Rspack 作为打包工具时，暂不支持使用 useLoader API。
-:::
-
-## 使用姿势
-
-```ts
-import { useLoader } from '@modern-js/runtime';
-```
-
-## 函数签名
-
-```ts
-type LoaderFn = (context: runtimeContext) => Promise<unknow>;
-type Options = {
-  onSuccess: (data: Record<string, any>) => void;
-  onError: (error: Error) => void;
-  initialData: Record<string, any>;
-  skip: boolean;
-  params: Record<string, any>;
-  static: boolean;
-};
-type ReturnData = {
-  data: Record<string, any>;
-  loading: boolean;
-  error: Error;
-  reload: (params?: Record<string, any>) => Promise<any> | undefined;
-  reloading: boolean;
-};
-
-function useLoader(loaderFn: LoaderFn, options: Options): ReturnData;
-```
-
-:::info
-`runtimeContext` 类型可以参考 [useRuntimeContext](/apis/app/runtime/core/use-runtime-context)。
-
-:::
-
-### 参数
-
-- `loaderFn`：用于加载数据的函数，返回 Promise。
-- `options`：可选配置项。
-  - `onSuccess`：执行成功的回调。
-  - `onError`：执行失败的回调。
-  - `initialData`：首次执行前的初始数据，对应返回值中的 `data` 字段。
-  - `skip`：当值为 `true` 时，函数不执行。
-  - `params`：当 `params` 序列化结果发生改变时，函数会重新执行。同时，`params` 也会作为函数的第二个参数被传入。
-  - `static`：当值为 `true` 时，`useLoader` 用于 [SSG](/guides/basic-features/render/ssg) 编译阶段数据的获取。
-
-### 返回值
-
-- `data`：执行成功时的返回数据。
-- `loading`：表示函数是否处于执行过程中。
-- `error`：函数执行失败时的错误信息。
-- `reload`：调用后可以重新执行函数。
-  - `params`：当值为 `undefined` 时，函数执行时将复用上次的值；否则会使用新的值重新执行函数。
-- `reloading`：调用 `reload` 的执行过程中，`reloading` 值为 `true`。
-
-## 示例
-
-```ts
-function Container() {
-  const { data, error, loading } = useLoader(
-    async (context, params) => {
-      console.log(params) // nicole
-      return fetch(user);
-    },
-    {
-      onSuccess: data => {
-        console.log('I did success:(',  data);
-      },
-      onError: error => {
-        console.log('I met error:)',  error);
-      },
-      initialData: { name: 'nicole', gender: 'female' },
-      params: 'nicole'
-    }
-  );
-
-  return ...;
-}
-```

package/docs/zh/apis/app/runtime/core/use-module-apps.mdx

@@ -1,179 +0,0 @@
----
-title: useModuleApps
----
-# useModuleApps
-
-返回所有微前端子应用的 React 组件，用于可自由控制路由。
-
-## 使用姿势
-
-```tsx
-import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
-```
-
-## 函数签名
-
-`function useModuleApps(): Record<string, React.FC<any>>`
-
-分别返回包裹每个子应用后的 React 组件。
-
-## 示例
-
-需要先配置微前端子应用信息。
-
-import EnableMicroFrontend from "@site-docs/components/enable-micro-frontend";
-
-<EnableMicroFrontend />
-
-这里演示主应用为自控式路由的场景，全部场景参考 [体验微前端](/guides/topic-detail/micro-frontend/c02-development.html)
-```tsx title=App.tsx
-function App() {
-  const { apps, MApp, Table, Dashboard } = useModuleApps();
-
-  // 使用的不是 MApp 组件，需要使用 createBrowserRouter 来创建路由
-  const router = createBrowserRouter(
-    createRoutesFromElements(
-      <Route path="/" element={<AppLayout />}>
-        <Route key={'table'} path={'table/*'} element={<Table />} />
-        <Route key={'dashboard'} path={'dashboard/*'} element={<Dashboard />} />
-      </Route>
-    )
-  );
-
-  return (
-    // 方法一：使用 MApp 自动根据配置的 activeWhen 参数加载子应用(本项目配置在 modern.config.ts 中)
-    // <BrowserRouter>
-    //   <MApp />
-    // </BrowserRouter>
-
-    // 方法二：手动写 Route 组件方式加载子应用，方便于需要鉴权等需要前置操作的场景
-    <>
-      <RouterProvider router={router} />
-    </>
-  );
-}
-
-defineConfig(App, {
-  masterApp: {
-    apps: [
-      {
-        // name 区分大小写，name 提供的是什么 useModuleApps 返回的就是什么
-        name: 'Table',
-        entry: 'http://127.0.0.1:8081/',
-      },
-      {
-        name: 'Dashboard',
-        entry: 'http://localhost:8082',
-      },
-    ],
-  },
-});
-```
-
-通过 `useModuleApps()` 获取到 `Table` 和 `Dashboard` 子应用组件（名称和配置里的 `name` 字段对应），之后就可以像使用普通的 React 组件一样去加载子应用。
-
-### 集中式路由
-
-**集中式路由** 是将子应用的激活路由集中配置的方式。我们给子应用列表信息添加 `activeWhen` 字段来启用 **集中式路由**。
-
-import MicroRuntimeConfig from "@site-docs/components/micro-runtime-config";
-
-<MicroRuntimeConfig />
-
-然后在主应用中使用 `useModuleApp` 方法获取 `MApp` 组件, 并在主应用渲染 `MApp`。
-
-```tsx title=主应用：App.tsx
-import { useModuleApp } from '@modern-js/plugin-runtime';
-
-function App() {
-  const { MApp } = useModuleApps();
-
-  return (
-    <div>
-      <MApp />
-    </div>
-  );
-}
-
-defineConfig(App, {
-  masterApp: {
-    apps: [
-      {
-        // name 区分大小写，name 提供的是什么 useModuleApps 返回的就是什么
-        name: 'Table',
-        activeWhen: '/table',
-        entry: 'http://127.0.0.1:8081/',
-      },
-      {
-        name: 'Dashboard',
-        activeWhen: '/dashboard',
-        entry: 'http://localhost:8082',
-      },
-    ],
-  },
-});
-```
-
-这样启动应用后，访问 `/dashboard` 路由，会渲染 `Dashboard` 子应用，访问 `/table` 路由，会渲染 `Table` 子应用。
-
-## 加载动画
-
-可以通过以下方式，自定义组件加载过程的过渡动画。
-
-```js title="App.tsx"
-import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
-
-import { RouterProvider, Route, createBrowserRouter, createRoutesFromElements, BrowserRouter, Link, Outlet } from '@modern-js/runtime/router';
-
-const AppLayout = () => (
-  <>
-    <div><Link to={'/table'}>加载约定式路由子应用</Link></div>
-    <div><Link to={'/dashboard'}>加载自控式路由子应用</Link></div>
-    <div><Link to={'/'}>卸载子应用</Link></div>
-    <Outlet />
-  </>
-)
-
-export default () => {
-  const { apps } = useModuleApps();
-
-  // 使用的不是 MApp 组件，需要使用 createBrowserRouter 来创建路由
-  const router = createBrowserRouter(
-    createRoutesFromElements(
-      <Route path="/" element={<AppLayout />}>
-        {apps.map(app => {
-          const { Component } = app;
-          // 模糊匹配，path 需要写成类似 abc/* 的模式
-          return (
-            <Route
-              key={app.name}
-              path={`${app.name.toLowerCase()}/*`}
-              element={
-              <Component
-                loadable={{
-                  loading: ({ pastDelay, error }: any) => {
-                    if (error) {
-                      return <div>error: {error?.message}</div>;
-                    } else if (pastDelay) {
-                      return <div>loading</div>;
-                    } else {
-                      return null;
-                    }
-                  },
-                }}
-              />
-              }
-            />
-          )
-        })}
-      </Route>
-    )
-  );
-
-  return (
-    <>
-      <RouterProvider router={router} />
-    </>
-  );
-};
-```