diff --git a/.changeset/angry-hats-jog.md b/.changeset/angry-hats-jog.md new file mode 100644 index 000000000000..f3e10a5607fd --- /dev/null +++ b/.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 属性的描述 diff --git a/packages/cli/core/src/types/context.ts b/packages/cli/core/src/types/context.ts index ba76927cca9f..3d90515d5318 100644 --- a/packages/cli/core/src/types/context.ts +++ b/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; } diff --git a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/extend.mdx b/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/extend.mdx index 4129405213c1..c8f1ad240722 100644 --- a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/extend.mdx +++ b/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/extend.mdx @@ -1,5 +1,4 @@ --- -title: Extending sidebar_position: 5 --- diff --git a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/hook-list.mdx b/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/hook-list.mdx index 3e3b0da02cb8..74c75c537e7f 100644 --- a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/hook-list.mdx +++ b/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/hook-list.mdx @@ -1,5 +1,4 @@ --- -title: Hook List sidebar_position: 8 --- diff --git a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/hook.mdx b/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/hook.mdx index d76448f90b06..0adb0b1b15ce 100644 --- a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/hook.mdx +++ b/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. diff --git a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/implement.mdx b/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/implement.mdx index a61f356b68d8..40bccd41a466 100644 --- a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/implement.mdx +++ b/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. diff --git a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/introduction.mdx b/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/introduction.mdx index 412c21044bfd..557b033e80a9 100644 --- a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/introduction.mdx +++ b/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 diff --git a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/lifecycle.mdx b/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/lifecycle.mdx index a0c87f4b1f83..c9b6a99de1bf 100644 --- a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/lifecycle.mdx +++ b/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. diff --git a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/plugin-api.mdx b/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/plugin-api.mdx index 27bf39837ae3..8d46e46bdecf 100644 --- a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/plugin-api.mdx +++ b/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. +::: diff --git a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/relationship.mdx b/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/relationship.mdx index 348d3df5ccf8..aa8140ffee2b 100644 --- a/packages/document/main-doc/docs/en/guides/topic-detail/framework-plugin/relationship.mdx +++ b/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: diff --git a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/extend.mdx b/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/extend.mdx index edffcd9216f9..89aadcec6001 100644 --- a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/extend.mdx +++ b/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/extend.mdx @@ -1,5 +1,4 @@ --- -title: 扩展插件 Hook sidebar_position: 5 --- diff --git a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/hook-list.mdx b/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/hook-list.mdx index 86e593d973bf..52bcc0e449ae 100644 --- a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/hook-list.mdx +++ b/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/hook-list.mdx @@ -1,5 +1,4 @@ --- -title: Hook 列表 sidebar_position: 8 --- diff --git a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/hook.mdx b/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/hook.mdx index b1bed13469f7..5fb5f0a4e7b9 100644 --- a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/hook.mdx +++ b/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 的工作模式。 diff --git a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/implement.mdx b/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/implement.mdx index 1cf0c44aa9ae..f7eaa81e7068 100644 --- a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/implement.mdx +++ b/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/implement.mdx @@ -1,5 +1,4 @@ --- -title: 如何编写插件 sidebar_position: 3 --- diff --git a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/introduction.mdx b/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/introduction.mdx index 0b3c2f3791da..d6f88474b469 100644 --- a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/introduction.mdx +++ b/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/introduction.mdx @@ -1,7 +1,7 @@ --- -title: 介绍 sidebar_position: 1 --- + # 介绍 ## Modern.js 插件系统 diff --git a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/lifecycle.mdx b/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/lifecycle.mdx index a795ac859649..b40b9b92990f 100644 --- a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/lifecycle.mdx +++ b/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 三个阶段。 diff --git a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/plugin-api.mdx b/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/plugin-api.mdx index b35878f028ef..f1be9f6d34ac 100644 --- a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/plugin-api.mdx +++ b/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，否则可能会导致框架内部的运行逻辑出错。 +::: diff --git a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/relationship.mdx b/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/relationship.mdx index 18d5153ed6f3..2beccaf7bf82 100644 --- a/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/relationship.mdx +++ b/packages/document/main-doc/docs/zh/guides/topic-detail/framework-plugin/relationship.mdx @@ -1,7 +1,7 @@ --- -title: 插件之间的关系 sidebar_position: 4 --- + # 插件之间的关系 Modern.js 的插件配置对象提供了一系列的字段，用于控制插件顺序、互斥等能力，可用的字段如下：