---
title: Hook 列表
sidebar_position: 8
---

# Hook 列表

在 Modern.js 中暴露了三类插件：CLI、Runtime、Server。下面列举下各类中的 Hook：

## CLI

### `beforeConfig`

- 功能：运行收集配置前的任务
- 执行阶段：收集配置前
- Hook 模型：AsyncWorkflow
- 类型：`AsyncWorkflow<void, void>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      beforeConfig: () => {
        // do something
      },
    };
  },
});
```

### `config`

- 功能：收集配置
- 执行阶段：解析完 `modern.config.ts` 中的配置之后
- Hook 模型：ParallelWorkflow
- 类型：`ParallelWorkflow<void, unknown>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      config: () => {
        return {
          /** some config */
        };
      },
    };
  },
});
```

这里返回的配置信息，会被收集和统一处理合并。

### `validateSchema`

- 功能：收集各个插件中配置的用来校验用户配置的 [JSON Schema](https://json-schema.org/)
- 执行阶段：`config` Hook 运行完之后。
- Hook 模型：ParallelWorkflow
- 类型：`ParallelWorkflow<void, unknown>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      validateSchema: () => {
        return {
          // target is field
          target: 'foo',
          schema: {
            type: 'string',
          },
        };
      },
    };
  },
});
```

这里返回的 JSON Schema 会用来校验 `modern.config.js` 中的配置信息。

比如这里返回：

```json
{
  "target": "foo",
  "schema": {
    "type": "string"
  }
}
```

就可以在 `modern.config.ts` 中这样配置：

```ts title="modern.config.ts"
export default defineConfig({
  foo: 'test',
});
```

如果是别的类型，校验就不通过会报错，比如这样：

```ts title="modern.config.ts"
export default defineConfig({
  foo: {},
});
```

就会报错：

```sh
$ modern dev
  1 | {
> 2 |   "foo": {},
    |   ^^^^^  Property foo is not expected to be here
```

### `prepare`

- 功能：运行主流程的前置准备流程
- 执行阶段：校验完配置之后
- Hook 模型：AsyncWorkflow
- 类型：`AsyncWorkflow<void, void>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      prepare: () => {
        // do something
      },
    };
  },
});
```

### `afterPrepare`

- 功能：运行前置准备流程的之后的任务
- 执行阶段：前置准备流程之后
- Hook 模型：AsyncWorkflow
- 类型：`AsyncWorkflow<void, void>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      afterPrepare: () => {
        // do something
      },
    };
  },
});
```

### `commands`

- 功能：为 command 添加新的命令
- 执行阶段：`prepare` Hook 运行完之后
- Hook 模型：AsyncWorkflow
- 类型：`AsyncWorkflow<{ program: Command; }, void>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      commands: ({ program }) => {
        program.command('foo').action(async () => {
          // do something
          console.log('foo');
        });
      },
    };
  },
});
```

将上面这个插件添加到 `modern.config.ts` 中：

```ts title="modern.config.ts"
import myPlugin from './config/plugin/myPlugin';

export default defineConfig({
  plugins: [myPlugin()],
});
```

运行 `modern foo` 就可以看到控制台输出：

```sh
$ modern foo
foo
```

### `beforeExit`

- 功能：在退出进程前，重置一些文件状态
- 执行阶段：进程退出之前
- Hook 模型：Workflow
- 类型：`Workflow<void, void>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      beforeExit: () => {
        // do something
      },
    };
  },
});
```

:::tip
由于 Node.js 中退出进程时的回调函数是同步的，所以 `beforeExit` Hook 的类型是 `Workflow`，不能执行异步操作。
:::

### `beforeDev`

- 功能：运行 dev 主流程的之前的任务
- 执行阶段：`dev` 命令运行时，项目开始启动前执行
- Hook 模型：AsyncWorkflow
- 类型：`AsyncWorkflow<void, unknown>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      beforeDev: () => {
        // do something
      },
    };
  },
});
```

### `afterDev`

- 功能：运行 dev 主流程的之后的任务
- 执行阶段：运行 `dev` 命令时，每一次编译完成后执行
- Hook 模型：AsyncWorkflow
- 类型：`AsyncWorkflow<{ isFirstCompile: boolean }, unknown>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      afterDev: () => {
        // do something
      },
    };
  },
});
```

`afterDev` 会在每一次编译完成后执行，你可以通过 `isFirstCompile` 参数来判断是否为首次编译：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      afterDev: ({ isFirstCompile }) => {
        if (isFirstCompile) {
          // do something
        }
      },
    };
  },
});
```

### `beforeCreateCompiler`

- 功能：在中间件函数中可以拿到创建 Webpack Compiler 的 Webpack 配置
- 执行阶段：创建 Webpack Compiler 之前执行
- Hook 模型：AsyncWorkflow
- 类型：`AsyncWorkflow<{ webpackConfigs: Configuration[];}, unknown>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      beforeCreateCompiler: ({ webpackConfigs }) => {
        // do something
      },
    };
  },
});
```

### `afterCreateCompiler`

- 功能：在中间件函数中可以拿到创建的 Webpack Compiler
- 执行阶段：创建 Webpack Compiler 之后执行
- Hook 模型：AsyncWorkflow
- 类型：`AsyncWorkflow<{ compiler: Compiler | MultiCompiler | undefined; }, unknown>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      afterCreateCompiler: ({ compiler }) => {
        // do something
      },
    };
  },
});
```

### `beforePrintInstructions`

- 功能：在中间件函数中可以拿到即将打印的日志信息，并对其进行修改
- 执行阶段：打印日志信息之前执行
- Hook 模型：AsyncWaterfall
- 类型：`AsyncWaterfall<{ instructions: string }>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      beforePrintInstructions: ({ instructions }) => {
        // do something
        return {
          instructions: [...instructions, 'some new message'],
        };
      },
    };
  },
});
```

### `beforeBuild`

- 功能：运行 build 主流程的之前的任务，可以拿到构建的 Webpack 配置
- 执行阶段：`build` 命令运行时，项目构建启动前执行
- Hook 模型：AsyncWorkflow
- 类型：`AsyncWorkflow<{ webpackConfigs: Configuration[]; }>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      beforeBuild: () => {
        // do something
      },
    };
  },
});
```

### `afterBuild`

- 功能：运行 build 主流程的之后的任务
- 执行阶段：`build` 命令运行时，项目构建完成之后执行
- Hook 模型：AsyncWorkflow
- 类型：`AsyncWorkflow<void, unknown>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      afterBuild: () => {
        // do something
      },
    };
  },
});
```

### `modifyEntryImports`

- 功能：用于修改、添加生成入口文件中的 `import` 语句
- 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
- Hook 模型：AsyncWaterfall
- 类型：`AsyncWaterfall<{ imports: ImportStatement[]; entrypoint: Entrypoint; }>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      modifyEntryImports({ entrypoint, imports }) {
        // 添加 `import React from 'React'`
        imports.push({
          value: 'react',
          specifiers: [
            {
              imported: 'unmountComponentAtNode',
            },
          ],
        });

        return { entrypoint, imports };
      },
    };
  },
});
```

### `modifyEntryExport`

- 功能：用于修改生成入口文件中的 `export` 语句
- 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
- Hook 模型：AsyncWaterfall
- 类型：`AsyncWaterfall<{ entrypoint: Entrypoint; exportStatement: string; }>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      modifyEntryExport({ entrypoint, exportStatement }) {
        return {
          entrypoint,
          exportStatement: [`export const foo = 'test'`, exportStatement].join(
            '\n',
          ),
        };
      },
    };
  },
});
```

### `modifyEntryRuntimePlugins`

- 功能：用于添加、修改生成入口文件中的 [Runtime 插件](#Runtime)
- 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
- Hook 模型：AsyncWaterfall
- 类型：`AsyncWaterfall<{ entrypoint: Entrypoint; plugins: RuntimePlugin[]; }>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      modifyEntryRuntimePlugins({ entrypoint, plugins }) {
        const name = 'customPlugin';
        const options = {
          /** 可序列化的内容 */
        };

        return {
          plugins: [
            ...plugins,
            {
              name,
              options: JSON.stringify(options),
            },
          ],
        };
      },
    };
  },
});
```

### `modifyEntryRenderFunction`

- 功能：用于修改生成入口文件中 `render` 函数
- 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
- Hook 模型：AsyncWaterfall
- 类型：`AsyncWaterfall<{ entrypoint: Entrypoint; code: string; }>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      modifyEntryRenderFunction({ entrypoint, code }) {
        const customRender = `/** render function body */`;
        return {
          entrypoint,
          code: customRender,
        };
      },
    };
  },
});
```

### `modifyFileSystemRoutes`

- 功能：用于修改生成前端页面路由文件中的内容，内容都是需要可序列化的
- 执行阶段：生成前端路由文件之前，[`prepare`](#prepare) 阶段触发
- Hook 模型：AsyncWaterfall
- 类型：`AsyncWaterfall<{ entrypoint: Entrypoint; routes: Route[]; }>`
- 使用示例：

```tsx
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      modifyFileSystemRoutes({ entrypoint, routes }) {
        return {
          entrypoint,
          routes: [
            ...routes,
            {
              path: '/custom_page',
              component: require.resolve('./Component'),
              exact: true,
            },
          ],
        };
      },
    };
  },
});
```

这样就为前端新增了一个页面路由。

### `modifyServerRoutes`

- 功能：用于修改生成服务器路由中的内容
- 执行阶段：生成 Server 路由文件之前，[`prepare`](#prepare) 阶段触发
- Hook 模型：AsyncWaterfall
- 类型：`AsyncWaterfall<{ routes: ServerRoute[]; }>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      modifyServerRoutes({ routes }) {
        return {
          routes: [
            ...routes,
            {
              urlPath: '/api/foo',
              isApi: true,
              entryPath: '',
              isSPA: false,
              isSSR: false,
            },
          ],
        };
      },
    };
  },
});
```

### `modifyAsyncEntry`

- 功能：用于修改包裹入口文件的异步模块，参见 [source.enableAsyncEntry](/configure/app/source/enable-async-entry)
- 执行阶段：生成入口文件之前，[`prepare`](#prepare) 阶段触发
- Hook 模型：AsyncWaterfall
- 类型：`AsyncWaterfall<{ entrypoint: Entrypoint; code: string; }>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      modifyAsyncEntry({ entrypoint, code }) {
        const customCode = `console.log('hello');`;
        return {
          entrypoint,
          code: `${customCode}${code}`,
        };
      },
    };
  },
});
```

### `htmlPartials`

- 功能：用于定制生成的 HTML 页面模版
- 执行阶段：[`prepare`](#prepare) 阶段触发
- Hook 模型：AsyncWaterfall
- 类型：`AsyncWaterfall<{ entrypoint: Entrypoint; partials: HtmlPartials; }>`
- 使用示例：

```ts
import type { CliPlugin } from '@modern-js/core';

export default (): CliPlugin => ({
  setup(api) {
    return {
      async htmlPartials({ entrypoint, partials }) {
        partials.head.push('<script>console.log("test")</script>');
        return {
          entrypoint,
          partials,
        };
      },
    };
  },
});
```

这样就为 HTML 模版中新增了一个 Script 标签。

{/* ## Server

:::note
目前 Server 插件还未完全开放，API 不保证稳定，使用需谨慎。

:::

应用工程中的 Server 部分也支持了插件。其中的 Hook 将会提供一些特定阶段调用和特殊功能的 Hook。

### `create`

- 功能：在中间件函数中会拿到 Server 初始化用到的指标测量工具配置 `measureOptions` 和日志工具配置 `loggerOptions`，并返回自定义的指标测量工具 `measure` 和日志工具配置 `logger`
- 执行阶段：Server 初始化
- Hook 模型：AsyncPipeline
- 类型：`AsyncPipeline<ServerInitInput, InitExtension>`
- 使用示例：

```ts
import type { ServerPlugin } from '@modern-js/server-core';

export default (): ServerPlugin => ({
  setup(api) {
    return {
      create: ({ measureOptions, loggerOptions }) => {
        // do something
      },
    };
  },
});
```

### `prepareWebServer`

- 功能：设置 Web 路由的处理函数，在中间件函数中可以拿到 Web Server 的前置中间件
- 执行阶段：在请求到达的时候
- Hook 模型：AsyncPipeline
- 类型：`AsyncPipeline<WebServerStartInput, Adapter>`
- 使用示例：

```ts
import type { ServerPlugin } from '@modern-js/server-core';

export default (): ServerPlugin => ({
  setup(api) {
    return {
      prepareWebServer: ({ middleware }) => {
        // do something

        return (req, res) => {
          // do response
        };
      },
    };
  },
});
```

### `prepareApiServer`

- 功能：设置 API 路由的处理函数，在中间件函数中可以拿到 API Server 的前置中间件
- 执行阶段：请求到达并且 match bff basename 之后执行
- Hook 模型：AsyncPipeline
- 类型：`AsyncPipeline<APIServerStartInput, Adapter>`
- 使用示例：

```ts
import type { ServerPlugin } from '@modern-js/server-core';

export default (): ServerPlugin => ({
  setup(api) {
    return {
      prepareApiServer: ({ middleware }) => {
        // do something

        return (req, res) => {
          // do response
        };
      },
    };
  },
});
```*/}

## Runtime

:::note
目前 Runtime 插件还未完全开放，API 不保证稳定，使用需谨慎。

:::

Runtime 插件主要用于开发者修改需要渲染的组件。

### `init`

- 功能：执行 `App.init`
- 执行阶段：渲染（SSR/CSR）
- Hook 模型：AsyncPipeline
- 类型：`AsyncPipeline<{ context: RuntimeContext; }, unknown>`
- 使用示例：

```ts
import type { Plugin } from '@modern-js/runtime';

export default (): Plugin => ({
  setup(api) {
    return {
      init({ context }, next) {
        // do something
        return next({ context });
      },
    };
  },
});
```

### `hoc`

- 功能：修改需要渲染的组件
- 执行阶段：渲染（SSR/CSR）
- Hook 模型：Pipeline
- 类型：`Pipeline<{ App: React.ComponentType<any>; }, React.ComponentType<any>>`
- 使用示例：

:::note
使用 hoc 钩子时，需要把原来的 App 组件的静态属性拷贝到新的组件上，并透传 props.
:::

```ts
import { createContext } from 'react';
import type { Plugin } from '@modern-js/runtime';
import hoistNonReactStatics from 'hoist-non-react-statics';

export default (): Plugin => ({
  setup(api) {
    const FooContext = createContext('');
    return {
      hoc({ App }, next) {
        const AppWrapper = (props: any) => {
          return (
            <FooContext.Provider store={'test'}>
              <App {...props} />
            </FooContext.Provider>
          );
        };
        return next({
          App: hoistNonReactStatics(AppWrapper, App),
        });
      },
    };
  },
});
```

{/* ### `provide`

- 功能：修改需要渲染的 Element
- 执行阶段：渲染（SSR/CSR）
- Hook 模型：Pipeline
- 类型：`Pipeline<{ element: JSX.Element; props: AppProps; context: RuntimeContext }, JSX.Element>`
- 使用示例：

```ts
import { createContext } from 'react';
import type { Plugin } from '@modern-js/runtime';

export default (): Plugin => ({
  setup(api) {
    const FooContext = createContext('');

    return {
      provide: ({ element }) => <div>{element}</div>,
    };
  },
});
```

### `client`

- 功能：定制客户端渲染流程
- 执行阶段：在浏览器客户端渲染
- Hook 模型：AsyncPipeline
- 类型：`AsyncPipeline<{ App: React.ComponentType<any>; context?: RuntimeContext; rootElement: HTMLElement; }, void>`
- 使用示例：

```ts
import ReactDOM from 'react-dom';
import type { Plugin } from '@modern-js/runtime';

export default (): Plugin => ({
  setup(api) {
    return {
      client: async ({ App, rootElement }) => {
        ReactDOM.render(
          React.createElement(App, { context: { foo: 'test' } }),
          rootElement,
        );
      },
    };
  },
});
```

### `server`

- 功能：定制服务器端渲染流程
- 执行阶段：SSR
- Hook 模型：AsyncPipeline
- 类型：`AsyncPipeline<{ App: React.ComponentType<any>; context?: RuntimeContext; }, string>`
- 使用示例：

```ts
import ReactDomServer from 'react-dom/server';
import type { Plugin } from '@modern-js/runtime';

export default (): Plugin => ({
  setup(api) {
    return {
      server({ App, context }) {
        return ReactDomServer.renderToString(
          React.createElement(App, { context: { foo: 'test' } }),
        );
      },
    };
  },
});
```*/}
