@modern-js/main-doc 2.69.4 → 3.0.0-alpha.0

package/docs/en/tutorials/first-app/c07-container.mdx

@@ -1,281 +0,0 @@
----
-title: Add Container
----
-# Add Container
-
-import { Tabs, Tab as TabItem } from "@theme";
-
-In the previous chapter, we initially introduced the **model** to split this part of the logic from the UI component. The `page.tsx` no longer contains UI-independent business logic implementation details, and only needs to use the Model to implement the same function.
-
-In this chapter, we will further use the business logic of implementation in Model to let `page.tsx` and `archived/page.tsx` get the same data. And implementation Archive button, click the button to display the point of contact archive only in the Archives list, not in the All list.
-
-## Use the full Model
-
-Because the two pages need to share the same set of state (point of contact tabular data, point of contact is archived or not), both need to contain the logic to load the initial data, so we need to complete the data acquisition at a higher level.
-
-Modern.js support obtaining data through Data Loader in `layout.tsx`, we first move the data acquisition part of the code to `src/routes/layout.tsx`:
-
-```ts title="src/routes/layout.data.ts"
-export type LoaderData = {
-  code: number;
-  data: {
-    name: string;
-    avatar: string;
-    email: string;
-  }[];
-};
-
-export const loader = async (): Promise<LoaderData> => {
-  const data = new Array(20).fill(0).map(() => {
-    const firstName = name.firstName();
-    return {
-      name: firstName,
-      avatar: `https://api.dicebear.com/7.x/pixel-art/svg?seed=${firstName}`,
-      email: internet.email(),
-    };
-  });
-
-  return {
-    code: 200,
-    data,
-  };
-};
-```
-
-```tsx title="src/routes/layout.tsx"
-import { name, internet } from 'faker';
-import {
-  Outlet,
-  useLoaderData,
-  useLocation,
-  useNavigate,
-} from '@modern-js/runtime/router';
-import { useState } from 'react';
-import { Radio, RadioChangeEvent } from 'antd';
-import { useModel } from '@modern-js/runtime/model';
-import contacts from '../models/contacts';
-import 'tailwindcss/base.css';
-import 'tailwindcss/components.css';
-import 'tailwindcss/utilities.css';
-import '../styles/utils.css';
-import type { LoaderData } from './layout.data';
-
-export default function Layout() {
-  const { data } = useLoaderData() as LoaderData;
-  const [{ items }, { setItems }] = useModel(contacts);
-  if (items.length === 0) {
-    setItems(data);
-  }
-
-  const navigate = useNavigate();
-  ...
-}
-```
-
-In `src/routes/page.tsx`, use Model directly to get data:
-
-```tsx
-import { Helmet } from '@modern-js/runtime/head';
-import { useModel } from '@modern-js/runtime/model';
-import { List } from 'antd';
-import Item from '../components/Item';
-import contacts from '../models/contacts';
-
-function Index() {
-  const [{ items }, { archive }] = useModel(contacts);
-
-  return (
-    <div className="container lg mx-auto">
-      <Helmet>
-        <title>All</title>
-      </Helmet>
-      <List
-        dataSource={items}
-        renderItem={info => (
-          <Item
-            key={info.name}
-            info={info}
-            onArchive={() => {
-              archive(info.email);
-            }}
-          />
-        )}
-      />
-    </div>
-  );
-}
-
-export default Index;
-```
-
-Also in `archived/page.tsx`, delete the original `mockData` logic and use the `archived` value computed in Model as the data source:
-
-```tsx
-import { Helmet } from '@modern-js/runtime/head';
-import { useModel } from '@modern-js/runtime/model';
-import { List } from 'antd';
-import Item from '../../components/Item';
-import contacts from '../../models/contacts';
-
-function Index() {
-  const [{ archived }, { archive }] = useModel(contacts);
-
-  return (
-    <div className="container lg mx-auto">
-      <Helmet>
-        <title>Archives</title>
-      </Helmet>
-      <List
-        dataSource={archived}
-        renderItem={info => (
-          <Item
-            key={info.name}
-            info={info}
-            onArchive={() => {
-              archive(info.email);
-            }}
-          />
-        )}
-      />
-    </div>
-  );
-}
-
-export default Index;
-```
-
-Execute `pnpm run dev`, visit `http://localhost:8080/`, click the Archive button, you can see the button grey out:
-
-![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c07-contacts-all.png)
-
-Next, click the top navigation and switch to the Archives list. You can find that the point of contact of **Archive** just now has appeared in the list:
-
-![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c07-contacts-archives.png)
-
-## Withdraw container components
-
-In the previous chapters, we split the business logic in the project into two layers, one is the **view component**, and the other is the **module**. The former is responsible for UI display, interaction, etc., and the latter is responsible for the implementation of UI-independent business logic, which specializes in managing state.
-
-Like `src/routes/page.tsx` and `src/routes/archives/page.tsx` use the component of the `useModel` API, which is responsible for linking the two layers of View and Model, similar to the role of the Controller in the traditional MVC architecture. In the Modern.js, we follow the habit and call them **Container**.
-
-The container component is recommended to be placed in a special `containers/` directory. We execute the following command to create a new file:
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/containers
-touch src/containers/Contacts.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/containers
-ni src/containers/Contacts.tsx
-```
-
-</TabItem>
-</Tabs>
-
-We extracted the common part of the original two `page.tsx`, and the code of `src/containers/Contacts.tsx` is as follows:
-
-```tsx
-import { Helmet } from '@modern-js/runtime/head';
-import { useModel } from '@modern-js/runtime/model';
-import { List } from 'antd';
-import Item from '../components/Item';
-import contacts from '../models/contacts';
-
-function Contacts({
-  title,
-  source,
-}: {
-  title: string;
-  source: 'items' | 'archived';
-}) {
-  const [state, { archive }] = useModel(contacts);
-
-  return (
-    <div className="container lg mx-auto">
-      <Helmet>
-        <title>{title}</title>
-      </Helmet>
-      <List
-        dataSource={state[source]}
-        renderItem={info => (
-          <Item
-            key={info.name}
-            info={info}
-            onArchive={() => {
-              archive(info.email);
-            }}
-          />
-        )}
-      />
-    </div>
-  );
-}
-
-export default Contacts;
-```
-
-Modify the code for `src/routes/page.tsx` and `src/routes/archives/page.tsx`:
-
-```tsx title="src/routes/page.tsx"
-import Contacts from '../containers/Contacts';
-
-function Index() {
-  return <Contacts title="All" source="items" />;
-}
-
-export default Index;
-```
-
-```tsx title="src/routes/archives/page.tsx"
-import Contacts from '../../containers/Contacts';
-
-function Index() {
-  return <Contacts title="Archives" source="archived" />;
-}
-
-export default Index;
-```
-
-The refactoring is complete, and the current project structure is:
-
-```bash
-.
-├── README.md
-├── dist
-├── modern.config.ts
-├── node_modules
-├── package.json
-├── pnpm-lock.yaml
-├── src
-│   ├── components
-│   │   ├── Avatar
-│   │   │   └── index.tsx
-│   │   └── Item
-│   │       └── index.tsx
-│   ├── containers
-│   │   └── Contacts.tsx
-│   ├── models
-│   │   └── contacts.ts
-│   ├── modern-app-env.d.ts
-│   ├── routes
-│   │   ├── archives
-│   │   │   └── page.tsx
-│   │   ├── layout.tsx
-│   │   └── page.tsx
-│   └── styles
-│       └── utils.css
-└── tsconfig.json
-```
-
-The **view components** in `components/` dir are in the form of directories, such as `Avatar/index.tsx`. And the **container components** in `containers/` dir are in the form of single files, such as `contacts.tsx`. **This is a best practice we recommend**.
-
-As mentioned in the chapter [Add UI component](./c02-component.mdx), the view component is in the form of a directory, because the view component is responsible for the implementation of UI display and interaction details, and can evolve in complexity. In the form of a directory, it is convenient to add sub-files, including dedicated resources (pictures, etc.), dedicated sub-components, CSS files, etc. You can reconstruct at will within this directory, considering only the smallest parts.
-
-The container component is only responsible for linkage and is a glue layer. The sophisticated business logic and implementation details are handed over to the View layer and the Model layer for implementation. The container component itself should be kept simple and clear, and should not contain complex implementation details, so there should be no internal structure. The single-file form is not only more concise, but also acts as a constraint, reminding developers not to write complicated container components.

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)。