@modern-js/main-doc 2.0.0-beta.0 → 2.0.0-beta.1

package/zh/configure/app/tools/jest.md

@@ -4,15 +4,13 @@ title: tools.jest
 sidebar_label: jest
 ---
 
-
+* 类型： `Object | Function`
+* 默认值：`{}`
 
 :::caution 注意
 需要先通过 `pnpm run new` 启用 单元测试 功能。
 :::
 
-* 类型： `Object | Function`
-* 默认值：`{}`
-
 对应 [Jest](https://jestjs.io/docs/configuration) 的配置，当为 `Object` 类型时，可以配置 Jest 所支持的所有底层配置 。
 
 ```js title=modern.config.js

package/zh/configure/app/tools/less.md

@@ -1,7 +1,6 @@
 ---
 title: tools.less
 sidebar_label: less
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/zh/configure/app/tools/minify-css.md

@@ -1,7 +1,6 @@
 ---
 title: tools.minifyCss
 sidebar_label: minifyCss
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/zh/configure/app/tools/postcss.md

@@ -1,7 +1,6 @@
 ---
 title: tools.postcss
 sidebar_label: postcss
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/zh/configure/app/tools/pug.md

@@ -1,7 +1,6 @@
 ---
 title: tools.pug
 sidebar_label: pug
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/zh/configure/app/tools/sass.md

@@ -1,7 +1,6 @@
 ---
 title: tools.sass
 sidebar_label: sass
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/zh/configure/app/tools/style-loader.md

@@ -1,7 +1,6 @@
 ---
 title: tools.styleLoader
 sidebar_label: styleLoader
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/zh/configure/app/tools/styled-components.md

@@ -1,7 +1,6 @@
 ---
 title: tools.styledComponents
 sidebar_label: styledComponents
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/zh/configure/app/tools/terser.md

@@ -1,7 +1,6 @@
 ---
 title: tools.terser
 sidebar_label: terser
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/zh/configure/app/tools/ts-checker.md

@@ -1,7 +1,6 @@
 ---
 title: tools.tsChecker
 sidebar_label: tsChecker
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/zh/configure/app/tools/ts-loader.md

@@ -1,7 +1,6 @@
 ---
 title: tools.tsLoader
 sidebar_label: tsLoader
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/zh/configure/app/tools/webpack-chain.md

@@ -1,7 +1,6 @@
 ---
 title: tools.webpackChain
 sidebar_label: webpackChain
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/zh/configure/app/tools/webpack.md

@@ -1,7 +1,6 @@
 ---
 title: tools.webpack
 sidebar_label: webpack
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/zh/configure/app/usage.md

@@ -4,9 +4,20 @@ sidebar_position: 0
 
 # 配置使用
 
-Modern.js 支持在 `modern.config.js` 配置文件或 `package.json` 文件中自定义配置选项。
+Modern.js 中有两种配置，一个是编译时配置，一个是服务端运行时配置。
 
-## 配置文件
+编译时配置可以在两个位置进行配置：
+
+- `package.json` 文件
+- 根路径下的 `modern.config.t(j)s` 文件
+
+:::warning 注意
+同一个配置不支持同时在 `package.json` 中和 `modern.config.t(j)s` 中配置。推荐在 `modern.config.t(j)s` 中进行配置。
+:::
+
+服务端运行时配置可以在根路径下的 `modern.server-runtime.config.t(j)s` 自定义配置选项。
+
+## 在配置文件中配置
 
 Modern.js 的配置文件定义在项目的根目录下，同时支持 `.js` 和 `.ts` 两种格式：
 
@@ -43,7 +54,7 @@ export default {
 
 我们推荐使用 .ts 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。
 
-从`@modern-js/app-tools`中导入 `defineConfig` 工具函数, 它会帮助你进行配置的类型推导和类型补全：
+从 `@modern-js/app-tools` 中导入 `defineConfig` 工具函数, 它会帮助你进行配置的类型推导和类型补全：
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -77,5 +88,5 @@ export default defineConfig({
 
 ## 注意事项
 
-- 不建议同时使用 `package.json` 和 `modern.config.js` 进行配置。如果同时使用了两者并出现配置冲突，modern.js 会在命令行进行提示。
+- 不建议同时使用 `package.json` 和 `modern.config.js` 进行配置。如果同时使用了两者并出现配置冲突，Modern.js 会在命令行进行提示。
 - `@modern-js/runtime` 导出了同名的 [defineConfig](/docs/apis/app/runtime/app/define-config) API，请注意区分。

package/zh/guides/advanced-features/bff/bff-server.md

@@ -48,7 +48,7 @@ export const post = async () => {
 ```
 
 :::info 补充信息
-`useContext` API 用于获取请求上下文，具体用法可以看 [API 文档](/docs/apis/app/runtime/bff-server/use-context)。
+`useContext` API 用于获取请求上下文，具体用法可以看 [API 文档](/docs/apis/app/runtime/bff/use-context)。
 :::
 
 接下来修改 `api/_app.ts`，手写一个中间件用于权限校验：

package/zh/guides/advanced-features/bff/frameworks.md

@@ -41,44 +41,6 @@ export default hook(({ addMiddleware }) => {
 });
 ```
 
-### [Nest](https://nestjs.com/)
-
-Nest 支持添加两种类型的内容：Express 的函数中间件和 Nest 中的 [Module](https:/docs.nestjs.com/modules)。
-
-Nest 的函数中间件的添加与 Express 段中的示例相同，Module 写法如下：
-
-```ts title=api/_app.ts
-import { hook } from "@modern-js/runtime/server";
-import { Module, Injectable, Controller, Get } from "@nestjs/common";
-
-@Controller("cats")
-export class CatsController {
-  constructor(private readonly catsService: CatsService) {}
-
-  @Get()
-  getHello() {
-    return this.catsService.getHello();
-  }
-}
-
-@Injectable()
-class CatsService {
-  getHello(): string {
-    return "Hello world!";
-  }
-}
-
-@Module({
-  controllers: [CatsController],
-  providers: [CatsService],
-})
-class CatsModule {}
-
-export default hook(({ addMiddleware }) => {
-  addMiddleware(CatsModule);
-});
-```
-
 ### [Koa](https://koajs.com/)
 
 Koa 函数写法下，可以通过在 `_app.[tj]s` 下添加 koa 的中间件：
@@ -94,36 +56,6 @@ export default hook(({ addMiddleware }) => {
 });
 ```
 
-### [Egg](https://eggjs.org/)
-
-Egg 函数写法下，可以通过在 `_app.[tj]s` 下添加 egg 的中间件：
-
-```ts
-import { hook } from "@modern-js/runtime/server";
-
-export default hook(({ addMiddleware }) => {
-  addMiddleware((options) => async (ctx, next) => {
-    console.info(`access url: ${ctx.url}`);
-    next();
-  });
-});
-```
-
-也可以添加 egg 第三方的中间件，且给第三方中间件注入参数：
-
-```ts
-import { hook } from "@modern-js/runtime/server";
-
-export default hook(({ addMiddleware }) => {
-  addMiddleware([
-    "eggMiddleware", // 此处为包名
-    {
-      name: "modernjs",
-    },
-  ]);
-});
-```
-
 ## 框架写法
 
 框架写法是一种使用框架分层结构来扩展 BFF 函数的方式。
@@ -163,75 +95,6 @@ app.use(async (req, res, next) => {
 export default app;
 ```
 
-如果需要在 BFF 函数注册路由后添加中间件，错误处理等，可以使用 [`afterLambdaRegisted`](/docs/apis/app/runtime/bff-server/after-lambda-registed) hook，该 hook 中的代码会在 BFF 函数注册路由后执行：
-```ts title="api/app.ts"
-const app = express();
-// 其他代码...
-export default app;
-
-export const afterLambdaRegisted = (app: Express) => {
-  const errorHandler = (
-    err: Error,
-    req: Request,
-    res: Response,
-    next: NextFunction,
-  ) => {
-    if (res.headersSent) {
-      return next(err);
-    }
-    res.status(500).send('some error message');
-  }
-  app.use(errHandler);
-}
-```
-
-### Nest
-
-Nest 虽然有定制的启动器，但本质与 Express、Koa 相同，所以 Modern.js 沿用了 Nest 定制启动器的默认入口：`api/main.ts`。
-
-按照 Nest 官方生成器生成的项目结构，在 Modern.js 中使用 Nest 框架写法时，`api/` 目录结构为：
-
-```markdown
-.
-├── app.controller.ts
-├── app.module.ts
-├── app.service.ts
-├── lambda
-│ └── hello.ts
-└── main.ts
-```
-
-其中 `api/main.ts` 中的内容与 Nest 官方生成器生成模版有所不同，应用工程中支持了两种模式：
-
-不包含内置 Module：
-
-```ts title=api/main.ts
-import { defineCustom } from "@modern-js/plugin-nest";
-import { NestFactory } from "@nestjs/core";
-import { Module } from "@nestjs/common";
-import { AppModule } from "./app.module";
-
-export default NestFactory.create(AppModule);
-```
-
-包含内置 Module：
-
-```ts title=api/main.ts
-import { defineCustom } from "@modern-js/plugin-nest";
-import { NestFactory } from "@nestjs/core";
-import { Module } from "@nestjs/common";
-import { AppModule } from "./app.module";
-
-export default defineCustom(async (modules) => {
-  @Module({
-    imports: [AppModule, ...modules],
-  })
-  class MainModule {}
-
-  return NestFactory.create(MainModule);
-});
-```
-
 ### Koa
 
 Koa 框架写法与 Express 类似，支持在 `app.[tj]s` 定义 API Server 的启动逻辑，执行应用的初始化工作，添加全局中间件，声明路由，扩展原有框架等。
@@ -262,87 +125,3 @@ app.use(async (ctx, next) => {
 
 export default app;
 ```
-
-### Egg
-
-#### 目录结构
-
-Modern.js 在 egg 框架写法中添加的初始样板文件较为简单，但 Modern.js 允许开发者使用 egg 框架约定的几乎所有文件（如中间件，定时器，控制器等）。
-
-```bash title="egg 框架写法的初始结构"
-.
-├── api/
-│   ├── app/
-│   │   └── middleware/
-│   │       └── trace.ts
-│   ├── config/
-│   │   └──  config.default.ts
-│   └── lambda/
-│       └── hello.ts
-├── src/
-├── modern.config.js
-├── package.json
-├── pnpm-lock.yaml
-├── tsconfig.json
-```
-
-#### Modern.js 的 一体化 BFF 函数 和 egg 中的 controller 有什么不同？
-
-- `lambda/` 下的 BFF 函数文件拥有定义路由和处理 API 逻辑两种功能，当你写一体化 BFF 函数的时候；就无需再写 controller 和 router。
-- `lambda/` 目录通过文件的目录结构定义路由，Egg 通过在 `router.ts` 文件编写代码定义路由。
-- `lambda/` 下可以写 BFF 函数，去处理 BFF 的逻辑；Egg 需要定义 class 声明 `controller`，BFF 函数的样板代码更少。
-- `lambda/` 下的文件可以使用 Modern.js 提供的 BFF API，如 `useContext`。
-- `lambda/` 下的 BFF 函数可以和 `egg` 的 `router`，`controller` 等混合使用，但通常不建议这么做。
-
-#### 调用 service
-
-在 egg 的框架写法下，同 egg 框架的使用方式一致，开发者也可以通过 `ctx` 调用定义的 service。
-
-假设有以下目录结构和文件：
-
-```js {4-5}
-.
-├── api/
-│   ├── app/
-│   │   └── service/
-│   │       └── user.ts
-│   ├── config/
-│   │   ├── config.default.ts
-│   └── lambda/
-│       └── hello.ts
-```
-
-```ts title=/app/service/user.ts
-import { Service } from "egg";
-
-class UserService extends Service {
-  async find(uid) {
-    const user = await this.ctx.db.query(
-      "select * from user where uid = ?",
-      uid
-    );
-    return user;
-  }
-}
-
-export default UserService;
-```
-
-在 `lambda` 目录下定义的 BFF 函数中，可以使用 `useContext` API 获取 egg 请求上下文
-
-```ts title=/api/lambda/hello.ts
-import { useContext } from "@modern-js/runtime/server";
-
-export const get = async () => {
-  const ctx = useContext();
-  const userId = ctx.params.id;
-  const user = await ctx.service.user.find(userId);
-  return user;
-};
-```
-
-#### 自定义启动逻辑
-
-在 egg 的框架写法中，同样支持启动自定义，`api/app[tj]s` 和 `agent.[tj]s` 遵循 egg 的规范。
-
-具体可见[启动自定义](https://eggjs.org/zh-cn/basics/app-start.html)。

package/zh/guides/advanced-features/code-split.md

@@ -35,7 +35,7 @@ function MyComponent() {
 }
 ```
 
-`loadable` 更多用法请见 [loadable API](/docs/apis/app/runtime/utility/loadable/loadable_)。
+`loadable` 更多用法请见 [loadable API](/docs/apis/app/runtime/utility/loadable)。
 
 :::info 注
 `loadable` 开箱即用的支持 SSR。

package/zh/guides/advanced-features/low-level.md

@@ -7,9 +7,9 @@ sidebar_position: 11
 
 Modern.js 内部默认集成了 [Babel](https://babeljs.io/)、[TypeScript](https://www.typescriptlang.org/)、[Webpack](https://webpack.js.org/)、[PostCSS](https://postcss.org/)、[Tailwind CSS](https://tailwindcss.com/) 等工具。通常情况下，默认配置能够满足大多业务开发需求。当有特殊需求时，可以通过底层配置来实现。
 
-以配置 Webpack 为例，只需要在 `modern.config.js` 中添加 [`tools.webpack`](/docs/configure/app/tools/webpack) 即可：
+以配置 Webpack 为例，只需要在 `modern.config.ts` 中添加 [`tools.webpack`](/docs/configure/app/tools/webpack) 即可：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   tools: {
     webpack: config => {

package/zh/guides/advanced-features/ssg.md

@@ -42,7 +42,7 @@ export default () => {
 
 SSG 和 SSR 一样，也是在 Node.js 环境中完成页面渲染，因此我们可以在开发阶段开启 SSR，提前在开发阶段验证 SSG 渲染效果：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   server: {
     ssr: process.env.NODE_ENV === 'development',
@@ -85,7 +85,7 @@ export default () => (
 
 例如上述入口中，包含两条客户端路由，分别是 `/` 和 `/foo`，设置 `output.ssg` 为 `true` 时，默认只会渲染入口路由即 `/`。如果我们希望同时开启 `/foo` 的 SSG 功能，可以这样配置：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   output: {
     ssg: {

package/zh/guides/advanced-features/ssr.md

@@ -30,7 +30,7 @@ Modern.js 打破传统的 SSR 开发模式，提供了用户无感的 SSR 开发
 不过，开发者仍然需要关注数据的兜底处理，例如 `null` 值或不符合预期的数据返回。避免在 SSR 时产生 React 渲染错误或是返回凌乱的渲染结果。
 
 :::info 补充信息
-关于 `useLoader` 的详细介绍可以参考[这里](/docs/apis/app/runtime/container/use-loader)。
+关于 `useLoader` 的详细介绍可以参考[这里](/docs/apis/app/runtime/core/use-loader)。
 :::
 
 ## 保持渲染一致
@@ -63,7 +63,7 @@ Warning: Expected server HTML to contain a matching <div> in <div>.
 关于注水逻辑请参考[这里](https://reactjs.org/docs/react-dom.html#hydrate)。
 :::
 
-应用需要保持 SSR 与 CSR 渲染结果的一致性，如果存在不一致的情况，说明这部分内容无需在 SSR 中进行渲染。Modern.js 为这类在 SSR 中不需要渲染的内容提供 [`<NoSSR>` 工具组件](/docs/apis/app/runtime/app/use-runtime-context)：
+应用需要保持 SSR 与 CSR 渲染结果的一致性，如果存在不一致的情况，说明这部分内容无需在 SSR 中进行渲染。Modern.js 为这类在 SSR 中不需要渲染的内容提供 [`<NoSSR>` 工具组件](/docs/apis/app/runtime/core/use-runtime-context)：
 
 ```ts
 import { NoSSR } from '@modern-js/runtime/ssr';
@@ -82,7 +82,7 @@ import { NoSSR } from '@modern-js/runtime/ssr';
 修改代码后，刷新页发现之前的 Waring 消失。打开浏览器开发者工具的 Network 窗口，查看返回的 HTML 文档是不包含 `NoSSR` 组件包裹的内容的。
 
 :::info 补充信息
-[`useRuntimeContext`](/docs/apis/app/runtime/app/use-runtime-context) 可以获取完整的请求信息，可以利用它保证 SSR 与 CSR 的渲染结果一致。
+[`useRuntimeContext`](/docs/apis/app/runtime/core/use-runtime-context) 可以获取完整的请求信息，可以利用它保证 SSR 与 CSR 的渲染结果一致。
 :::
 
 ## 关注内存泄漏
@@ -182,5 +182,5 @@ import { PreRender } from '@modern-js/runtime/ssr';
 可以想象，当 `interval` 设置为 1 时，用户可以在感知到实时数据的同时，拥有静态页面的响应体验。
 
 :::info 补充信息
-`PreRender` 的详细使用可以参考[这里](/docs/apis/app/runtime/app/pre-render)。
+`PreRender` 的详细使用可以参考[这里](/docs/apis/app/runtime/ssr/pre-render)。
 :::

package/zh/guides/basic-features/alias.md

@@ -54,7 +54,7 @@ Modern.js 也提供了自定义别名的方式，以添加 `@common` 别名为
 
 JavaScript 项目可以在 `modern.config.js` 中配置 [`source.alias`](/docs/configure/app/source/alias):
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   source: {
     alias: {

package/zh/guides/basic-features/css/postcss.md

@@ -70,7 +70,7 @@ sidebar_position: 3
 
   当需要修改 PostCSS 配置时，可以通过底层配置 [`tools.postcss`](/docs/configure/app/tools/postcss) 来实现，下面是一个示例：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   tools: {
     postcss: {

package/zh/guides/basic-features/css/tailwindcss.md

@@ -29,7 +29,7 @@ import 'tailwindcss/utilities.css';
 
 当需要自定义 Tailwind CSS 的 [theme](https://tailwindcss.com/docs/theme) 配置的时候，可以在配置 [`source.designSystem`](/docs/configure/app/source/design-system) 中修改，例如，颜色主题中增加一个 `primary`：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   source: {
     designSystem: {
@@ -45,7 +45,7 @@ export default defineConfig({
 
 当需要对 Tailwind CSS 做 [theme](https://tailwindcss.com/docs/theme) 以外的其他特殊配置时，可以在 [`tools.tailwindcss`](/docs/configure/app/tools/tailwindcss) 中配置，例如设置 `variants`：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   tools: {
     tailwindcss: {

package/zh/guides/basic-features/env-vars.md

@@ -28,8 +28,7 @@ if (true) {
 ```
 
 如果想在代码中使用除 `NODE_ENV` 以外的环境变量，可以在 [`source.define`](/docs/configure/app/source/define) 配置指定, 如下:
-
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   source: {
     envVars: ['VERSION']
@@ -63,7 +62,7 @@ VERSION=1.0.0
 
 Modern.js 支持在编译时设置代码中使用到的全局变量:
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   source: {
     globalVars: {

package/zh/guides/basic-features/proxy.md

@@ -7,7 +7,7 @@ sidebar_position: 5
 
 Modern.js 在 [`tools.devServer`](/docs/configure/app/tools/dev-server) 中提供了配置开发环境代理的方式。例如，将本地开发接口，代理到线上某个地址：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 import { defineConfig }  from '@modern-js/app-tools';
 
 export default defineConfig({
@@ -65,7 +65,7 @@ Modern.js 提供了开箱即用的全局代理插件 `@modern-js/plugin-proxy`
 
 通过配置 [`bff.proxy`](/docs/configure/app/bff/proxy) 可以代理 BFF API 请求到指定的服务上，和[开发环境代理](/docs/configure/app/dev/proxy)不同的是，它同样可以用在生产环境：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   bff: {
     proxy: {

package/zh/guides/topic-detail/compile-speed.md

@@ -51,7 +51,7 @@ npx modern build --analyze
 
 由于 `ts-loader` 需要进行额外的语法解析和类型检查，因此会导致项目编译速度变慢，请避免使用。
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   output: {
     // 移除这项配置
@@ -84,7 +84,7 @@ export default defineConfig({
 
 明确第三方依赖不需要 Polyfill 的情况下，可以将 `output.polyfill` 设置为 `usage`，根据代码中使用到的语法，按需注入所需的 Polyfill 代码，从而减少 Polyfill 的代码量。
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   output: {
     polyfill: 'usage',
@@ -106,7 +106,7 @@ export default defineConfig({
 
 比如禁用 SourceMap：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   tools: {
     webpackChain(chain, { env }) {
@@ -120,7 +120,7 @@ export default defineConfig({
 
 或是把开发环境的 SourceMap 格式设置为开销最小的 `eval` 格式：
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   tools: {
     webpackChain(chain, { env }) {
@@ -163,7 +163,7 @@ export default defineConfig({
 
 如果项目在生产环境下不需要 SourceMap，可以通过 `disableSourceMap` 配置项关闭，从而提升 build 构建的速度。
 
-```js title="modern.config.js"
+```typescript title="modern.config.ts"
 export default defineConfig({
   output: {
     disableSourceMap: true,

package/zh/guides/topic-detail/generator/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "项目生成器",
+  "position": 5
+}

package/zh/guides/topic-detail/generator/codesmith/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "开发微生成器",
+  "position": 5
+}

package/zh/guides/topic-detail/generator/codesmith/introduce.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 1
+---
+
+# 介绍

package/zh/guides/topic-detail/generator/config/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "工程方案配置",
+  "position": 3
+}