docs: add descriptions for AppContext properties (#4726)

.changeset/angry-hats-jog.md

@@ -0,0 +1,8 @@
+---
+'@modern-js/main-doc': patch
+'@modern-js/core': patch
+---
+
+docs: add descriptions for AppContext properties
+
+docs: 增加 AppContext 属性的描述

packages/cli/core/src/types/context.ts

@@ -7,38 +7,73 @@ import {
 } from '@modern-js/types';
 import { BuilderInstance } from '@modern-js/builder-shared';
 
-export type ToolsType =
-  | 'app-tools'
-  | 'module-tools'
-  | 'doc-tools'
-  | 'monorepo-tools';
+export type ToolsType = 'app-tools' | 'module-tools' | 'monorepo-tools';
 
 export interface IAppContext {
-  metaName: string; // name for generating conventional constants, such as .modern-js
+  /** name for generating conventional constants, such as .modern-js */
+  metaName: string;
+  /** Root directory of the current project */
   appDirectory: string;
+  /** Source code directory */
+  srcDirectory: string;
+  /** Directory for output files */
+  distDirectory: string;
+  /** Directory for API modules */
+  apiDirectory: string;
+  /** Directory for lambda modules */
+  lambdaDirectory: string;
+  /** Directory for shared modules */
+  sharedDirectory: string;
+  /** Directory for framework temp files */
+  internalDirectory: string;
+  /** node_modules directory */
+  nodeModulesDirectory: string;
+  /** Path to the configuration file */
   configFile: string | false;
+  /** Path to the server configuration file */
   serverConfigFile: string;
+  /** Currently registered server plugins */
   serverInternalPlugins: InternalPlugins;
+  /** IPv4 address of the current machine */
   ip?: string;
+  /** Port number of the development server */
   port?: number;
-  distDirectory: string;
-  toolsType?: ToolsType;
+  /** Name of the current project's package.json */
   packageName: string;
-  srcDirectory: string;
-  apiDirectory: string;
-  lambdaDirectory: string;
-  sharedDirectory: string;
-  nodeModulesDirectory: string;
-  internalDirectory: string;
+  /** Currently registered plugins */
   plugins: any[];
+  /** Information for entry points */
   entrypoints: Entrypoint[];
+  /** Selected entry points */
   checkedEntries: string[];
+  /** Information for server routes */
   serverRoutes: ServerRoute[];
-  htmlTemplates: HtmlTemplates;
+  /** Whether to use api only mode */
   apiOnly: boolean;
-  internalDirAlias: string;
-  internalSrcAlias: string;
+  /** The Builder instance */
   builder?: BuilderInstance;
+  /** Tools type of the current project */
+  toolsType?: ToolsType;
+  /** Type of the bundler being used */
   bundlerType?: 'webpack' | 'rspack' | 'esbuild';
+  /**
+   * The alias path for internal usage
+   * @private
+   */
+  internalDirAlias: string;
+  /**
+   * The alias path for internal usage
+   * @private
+   */
+  internalSrcAlias: string;
+  /**
+   * Information for HTML templates
+   * @private
+   */
+  htmlTemplates: HtmlTemplates;
+  /**
+   * Information for HTML templates by entry
+   * @private
+   */
   partialsByEntrypoint?: Record<string, HtmlPartials>;
 }

packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/extend.mdx

@@ -1,5 +1,4 @@
 ---
-title: Extending
 sidebar_position: 5
 ---
 

packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/hook-list.mdx

@@ -1,5 +1,4 @@
 ---
-title: Hook List
 sidebar_position: 8
 ---
 

packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/hook.mdx

@@ -1,7 +1,7 @@
 ---
-title: Hook Model
 sidebar_position: 2
 ---
+
 # Hook Model
 
 First, let's introduce some content about the basic plugin system in Modern.js, including the working mode of the Hook model, the operating mode of each Hook model, and the working mode of the Manager.

packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/implement.mdx

@@ -1,9 +1,8 @@
 ---
-title: Develop Plugins
 sidebar_position: 3
 ---
 
-# How to Develop Plugins
+# Develop Plugins
 
 The previous section introduced the Hook models used by Modern.js plugins, while this section describes how to develop plugins.
 

packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/introduction.mdx

@@ -1,7 +1,7 @@
 ---
-title: Introduction
 sidebar_position: 1
 ---
+
 # Introduction
 
 ## Modern.js Plugin System

packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/lifecycle.mdx

@@ -1,7 +1,7 @@
 ---
-title: Lifecycle
 sidebar_position: 1
 ---
+
 # Lifecycle
 
 Modern.js application has a complete lifecycle, including CLI, Server Side and Runtime three stages.

packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/plugin-api.mdx

@@ -1,5 +1,4 @@
 ---
-title: Plugin API
 sidebar_position: 6
 ---
 
@@ -79,26 +78,43 @@ Used to retrieve the runtime context of the application.
 const useAppContext: () => IAppContext;
 
 interface IAppContext {
+  /** Root directory of the current project */
   appDirectory: string;
+  /** Source code directory */
+  srcDirectory: string;
+  /** Directory for output files */
+  distDirectory: string;
+  /** Directory for shared modules */
+  sharedDirectory: string;
+  /** Directory for framework temp files */
+  internalDirectory: string;
+  /** node_modules directory */
+  nodeModulesDirectory: string;
+  /** Path to the configuration file */
   configFile: string | false;
+  /** IPv4 address of the current machine */
   ip?: string;
+  /** Port number of the development server */
   port?: number;
-  distDirectory: string;
+  /** Name of the current project's package.json */
   packageName: string;
-  srcDirectory: string;
-  sharedDirectory: string;
-  nodeModulesDirectory: string;
-  internalDirectory: string;
-  plugins: {
-    cli?: any;
-    server?: any;
-  }[];
+  /** Currently registered plugins */
+  plugins: any[];
+  /** Information for entry points */
   entrypoints: Entrypoint[];
+  /** Information for server routes */
   serverRoutes: ServerRoute[];
-  htmlTemplates: HtmlTemplates;
+  /** Tools type of the current project */
+  toolsType?: 'app-tools' | 'module-tools' | 'monorepo-tools';
+  /** Type of the bundler being used */
+  bundlerType?: 'webpack' | 'rspack' | 'esbuild';
 }
 ```
 
+:::tip
+Some fields in the AppContext are dynamically set and will change as the program runs. Therefore, when plugins read these fields at different times, they may get different values.
+:::
+
 ### useHookRunners
 
 Used to retrieve the executor of Hooks and trigger the execution of specific Hooks.
@@ -116,3 +132,7 @@ export const myPlugin = (): CliPlugin => ({
   },
 });
 ```
+
+:::tip
+Please avoid executing the built-in hooks, as it may break the internal execution logic of the framework.
+:::

packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/relationship.mdx

@@ -1,8 +1,8 @@
 ---
-title: Relationship
 sidebar_position: 4
 ---
-# Relationship between Plugins
+
+# Relationship
 
 The plugin configuration object in Modern.js provides a series of fields to control plugin order, mutual exclusion, and other capabilities. The available fields are as follows:
 

packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/extend.mdx

@@ -1,5 +1,4 @@
 ---
-title: 扩展插件 Hook
 sidebar_position: 5
 ---
 

packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/hook-list.mdx

@@ -1,5 +1,4 @@
 ---
-title: Hook 列表
 sidebar_position: 8
 ---
 

packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/hook.mdx

@@ -1,7 +1,7 @@
 ---
-title: Hook 模型
 sidebar_position: 2
 ---
+
 # Hook 模型
 
 首先介绍一下 Modern.js 的基础的插件系统中的一些内容，包括 Hook 模型的工作方式、各个 Hook 模型的运行模式、Manager 的工作模式。

packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/implement.mdx

@@ -1,5 +1,4 @@
 ---
-title: 如何编写插件
 sidebar_position: 3
 ---
 

packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/introduction.mdx

@@ -1,7 +1,7 @@
 ---
-title: 介绍
 sidebar_position: 1
 ---
+
 # 介绍
 
 ## Modern.js 插件系统

packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/lifecycle.mdx

@@ -1,7 +1,7 @@
 ---
-title: 生命周期
 sidebar_position: 1
 ---
+
 # 生命周期
 
 Modern.js 应用具有完整的生命周期，包括 CLI、Server Side 和 Runtime 三个阶段。

packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/plugin-api.mdx

@@ -1,5 +1,4 @@
 ---
-title: 插件 API
 sidebar_position: 6
 ---
 
@@ -79,26 +78,43 @@ interface NormalizedConfig {
 const useAppContext: () => IAppContext;
 
 interface IAppContext {
+  /** 当前项目的根目录 */
   appDirectory: string;
+  /** 源代码目录 */
+  srcDirectory: string;
+  /** 构建产出输出目录 */
+  distDirectory: string;
+  /** 公共模块目录 */
+  sharedDirectory: string;
+  /** 框架临时文件输出目录 */
+  internalDirectory: string;
+  /** node_modules 目录 */
+  nodeModulesDirectory: string;
+  /** 配置文件路径 */
   configFile: string | false;
+  /** 当前机器的 IPv4 地址 */
   ip?: string;
+  /** 开发服务器的端口号 */
   port?: number;
-  distDirectory: string;
+  /** 当前项目 package.json 的 name */
   packageName: string;
-  srcDirectory: string;
-  sharedDirectory: string;
-  nodeModulesDirectory: string;
-  internalDirectory: string;
-  plugins: {
-    cli?: any;
-    server?: any;
-  }[];
+  /** 当前注册的插件 */
+  plugins: any[];
+  /** 页面入口信息 */
   entrypoints: Entrypoint[];
+  /** 服务端路由信息 */
   serverRoutes: ServerRoute[];
-  htmlTemplates: HtmlTemplates;
+  /** 当前项目类型 */
+  toolsType?: 'app-tools' | 'module-tools' | 'monorepo-tools';
+  /** 当前使用的打包工具类型 */
+  bundlerType?: 'webpack' | 'rspack' | 'esbuild';
 }
 ```
 
+:::tip
+AppContext 中的部分字段是动态设置的，会随着程序的运行而变化。因此，当插件在不同的时机读取字段时，可能会获取到不同的值。
+:::
+
 ### useHookRunners
 
 用于获取 Hooks 的执行器，并触发特定的 Hook 执行。
@@ -116,3 +132,7 @@ export const myPlugin = (): CliPlugin => ({
   },
 });
 ```
+
+:::tip
+请尽量避免执行框架内置的 hooks，否则可能会导致框架内部的运行逻辑出错。
+:::

packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/relationship.mdx

@@ -1,7 +1,7 @@
 ---
-title: 插件之间的关系
 sidebar_position: 4
 ---
+
 # 插件之间的关系
 
 Modern.js 的插件配置对象提供了一系列的字段，用于控制插件顺序、互斥等能力，可用的字段如下：