@modern-js/main-doc 2.65.4 → 2.66.0

package/docs/en/plugin/plugin-system/hook.mdx

@@ -1,188 +0,0 @@
----
-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.
-
-Each Hook model is independent and can manage running functions independently.
-
-## Basic Working Mode
-
-Taking the Pipeline as an example, let's briefly introduce the working mode of the Hook model. Let's take a look at a simple example:
-
-
-```ts
-import { createPipeline } from '@modern-js/plugin';
-
-// 1. create
-const pipeline = createPipeline<number, number>();
-
-// 2. add function
-pipeline.use((count, next) => {
-  return next(count + 1);
-});
-pipeline.use((count, next) => {
-  return count * 2;
-});
-
-// 3. exec
-pipeline.run(1); // 4
-pipeline.run(5); // 12
-```
-
-In this example, a `Pipeline<number, number>` is created on line 3. This means that when you run it, you need to pass in a `number`, and you will get a `number` as a result, the type is:
-
-```ts
-(count: number, next: (nextCount: number) => number) => number;
-```
-
-The reason why there are only `number`s here is because we created a `Pipeline<number, number>`. If we had created a `Pipeline<number, string>`, then when we run it, we would pass in a `number` and get back a `string`. the type is:
-
-```ts
-(count: number, next: (nextCount: number) => string) => string;
-```
-
-After creating a Pipeline, you can add functions using the `use` method (lines 5 and 8). It is important to note that the order in which you add the functions is the order in which they will run by default.
-
-Within these functions, you can manipulate the `count` value and return a value. If you call the `next` function, the next function in the pipeline will run. For example, if you add three functions: `A`, `B`, and `C`, and you call `next` in function `A`, then function `B` will run. Similarly, if you call `next` in function `B`, then function `C` will run.
-
-In the example above, the first function added on line 5 calls `next`, which causes the second function added on line 8 to run. The return value of this function is the return value of the entire pipeline. If the first function does not call `next` and simply returns a value, then the pipeline will return that value without running any other functions.
-
-For example:
-
-```ts
-import { createPipeline } from '@modern-js/plugin';
-
-// 1. create
-const pipeline = createPipeline<number, number>();
-
-// 2. add function
-pipeline.use((count, next) => {
-  return count + 1;
-});
-pipeline.use((count, next) => {
-  return count * 2;
-});
-
-// 3. Run
-pipeline.run(1); // 2
-pipeline.run(5); // 6
-```
-
-If the first function does not call `next`, the second function will not run and the return value of the pipeline will be the return value of the first function.
-
-Finally, the way to run the Pipeline is simply to call `pipeline.run()`.
-
-
-## Differences between different Hook models
-
-The above section describes the general working mode of the Pipeline, and the working modes of other Hook models are similar. The main differences lie in the function type, execution order, and parameters.
-
-### Pipeline
-
-The example above describes the Pipeline, so we won't go into details here. In the Pipeline category, there are two subcategories: Sync and Async, which manage functions of either Sync or Async type, respectively.
-
-:::info
-If there are no functions in the Pipeline or all functions have called the `next` function, then you need to provide a value when running the Pipeline.
-:::
-
-
-```ts
-pipeline(
-  {},
-  {
-    onLast: () => {
-      // do something
-    },
-  },
-);
-```
-
-:::
-
-### Waterfall
-
-This model, as the name suggests, is characterized by the sequential passing of parameters, where the return value of the previous function becomes the input parameter of the next function. Let's look at an example::
-
-```ts
-import { createWaterfall } from '@modern-js/plugin';
-
-// 1. create
-const waterfall = createWaterfall<number>();
-
-// 2. add function
-waterfall.use(count => {
-  return count + 1;
-});
-waterfall.use(count => {
-  return count * 2;
-});
-
-// 3. exec
-waterfall.run(1); // 4
-waterfall.run(5); // 12
-```
-
-In this example, a `Waterfall<number>` type is created, which means that the input and output types of this model are the same. In this case, both the input and output types are `number`, the type is:
-
-```ts
-(count: number) => number;
-```
-
-At first glance, this example may seem to have the same functionality as the Pipeline above, but there are some important differences to note. Firstly, the functions managed by Waterfall do not have a `next` function as the second argument, so they cannot modify the execution order by calling `next` within the function. Secondly, the input and output types of the functions must be the same (unlike in the Pipeline where they can be different).
-
-Similarly to Pipeline, Waterfall has Sync and Async subcategories that respectively manage Sync and Async functions.
-
-### Workflow
-
-This Hook model is different from the two Hook models above in that there is no strong concept of passing parameters and return values in a sequential order. In this model, each function runs independently based on the same input parameter.
-
-for example:
-
-```ts
-import { createWorkflow } from '@modern-js/plugin';
-
-// 1. create
-const workflow = createWorkflow<number, number>();
-
-// 2. add plugin
-workflow.use(count => {
-  return count + 1;
-});
-workflow.use(count => {
-  return count * 2;
-});
-
-// 3. Run
-workflow.run(1); // [2, 2]
-workflow.run(5); // [6, 10]
-```
-
-In this example, two functions are added to the Workflow, so the result of running the Workflow is an array of the results of these two functions.
-
-Although there is no strong concept of passing parameters and return values in a sequential order in this model, there are still differences in the execution order. In the Workflow category, there are three subcategories: Sync, Async, and Parallel.
-
-The difference between them lies in the execution order of the functions. By default, they are all executed in the order they are added, but in Sync and Async mode, the execution order is strictly based on the order in which they are added, while in Parallel mode, a variant of Async mode, `Promise.all` is used to execute all the functions, while in Async mode, `await` is used to wait for the previous function to finish running.
-
-## Comparison of Hook models
-
-
-<div style={{ width: "100%", overflowX: "scroll" }}>
-<div style={{ width: "150%" }}>
-
-|                  | Function Type | Execution Order                                             | Source of Function Parameters                                                               | Source of Execution Returns | Preferred Task Type                                               | Function TS Type                                             |
-| ---------------- | ------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------ |
-| Pipeline         | Sync          | Executes the first added function by default, can execute subsequent functions through `next` | The parameters of the first function come from the input, while the parameters of subsequent functions come from the parameters passed to `next` | Returns from the first function | <ul><li>Needs to modify initial parameters</li><li>Needs to modify function execution order</li></ul> | `(input: I, next: Next<I, O>) => O`                          |
-| AsyncPipeline    | Sync/Async    | Executes the first added function by default, can execute subsequent functions through `next` | The parameters of the first function come from the input, while the parameters of subsequent functions come from the parameters passed to `next` | Returns from the first function | <ul><li>Needs to modify initial parameters</li><li>Needs to modify function execution order</li></ul> | `(input: I, next: AsyncNext<I, O>) => O ｜ Promise<O>`      |
-| Waterfall        | Sync          | Executes functions in order                                  | The parameters of the first function come from the input, while the parameters of subsequent functions come from the return value of the previous function | Returns from the last function | <ul><li>Needs to modify initial parameters</li><li>Does not need to modify function execution order</li></ul> | `(I: I) => I`                                               |
-| AsyncWaterfall   | Sync/Async    | Executes functions in order                                  | The parameters of the first function come from the input, while the parameters of subsequent functions come from the return value of the previous function | Returns from the last function | <ul><li>Needs to modify initial parameters</li><li>Does not need to modify function execution order</li></ul> | `(I: I) => I ｜ Promise<I>`                                 |
-| Workflow         | Sync          | Executes functions in order                                  | All function parameters come from the input                                                  | An array of all function returns | <ul><li>Does not need to modify initial parameters</li><li>Does not need to modify function execution order</li></ul> | `(I: I) => O`                                               |
-| AsyncWorkflow    | Sync/Async    | Executes functions in order                                  | All function parameters come from the input                                                  | An array of all function returns | <ul><li>Does not need to modify initial parameters</li><li>Does not need to modify function execution order</li></ul> | `(I: I) => O ｜ Promise<O>`                                 |
-| ParallelWorkFlow | Sync/Async    | Executes functions asynchronously                            | All function parameters come from the input                                                  | An array of all function returns | <ul><li>Does not need to modify initial parameters</li><li>Does not care about function execution order</li></ul>           | `(I: I) => O ｜ Promise<O>`                                 |
-
-</div>
-</div>
-
-"Workflow" and "Waterfall" are actually variants of the "Pipeline" model. While it's possible to implement "Workflow" and "Waterfall" using a specific writing style with "Pipeline", it can be more complicated with many implicit conventions. To make it easier to use, these two variants are provided to satisfy specific use cases.

package/docs/en/plugin/plugin-system/implement.mdx

@@ -1,243 +0,0 @@
----
-sidebar_position: 3
----
-
-# Develop Plugins
-
-The previous section introduced the Hook models used by Modern.js plugins, while this section describes how to develop plugins.
-
-## Implementing a Plugin
-
-A Modern.js plugin is an object that includes the following properties:
-
-- `name`: The name of the plugin, a unique identifier.
-- `setup`: The initialization function for the plugin, which only runs once. The `setup` function can return a Hooks object, which Modern.js executes at specific times.
-
-```ts
-const myPlugin = {
-  name: 'my-plugin',
-
-  setup() {
-    const foo = '1';
-
-    // return hook object
-    return {
-      afterBuild: () => {},
-    };
-  },
-};
-```
-
-In addition, plugins allow configuration of the execution order with other plugins. For more information, please refer to [Plugin Relationship](/plugin/plugin-system/relationship).
-
-### Plugin Types
-
-Modern.js supports various types of project development, such as application development (Modern.js Framework), module development (Modern.js Module), etc.
-
-To balance the differences and commonalities between various types of project development, Modern.js organizes plugins as shown in the following figure:
-
-![plugin-relationship](https://lf3-static.bytednsdoc.com/obj/eden-cn/eeeh7uhbepxlpe/modern-website/plugin-relationship.jpg)
-
-As shown in the figure, Modern.js roughly divides plugins into two categories:
-
-1. Common plugins: Plugins that only include some basic Hooks.
-
-2. Project plugins: Different project developments will extend their own Hooks, Config, etc. on the basis of common plugins.
-
-When using TypeScript, you can import built-in types such as `CliPlugin` to provide correct type inference for plugins.
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-const myPlugin: CliPlugin = {
-  name: 'my-plugin',
-
-  setup() {
-    const foo = '1';
-
-    return {
-      afterBuild: () => {},
-    };
-  },
-};
-```
-
-The above code is a general-purpose plugin, containing only some basic Hooks. Modern.js supports extending the definition of plugins through generics:
-
-```ts
-import type { CliPlugin, AppTools } from '@modern-js/app-tools';
-
-const myPlugin: CliPlugin<AppTools> = {
-  name: 'my-plugin',
-
-  setup() {
-    const foo = '1';
-
-    return {
-      afterBuild: () => {},
-    };
-  },
-};
-```
-
-If you look closely at the type `AppTools`, you can see that `AppTools` consists of 3 types.
-
-```ts
-type AppTools = {
-  hooks: AppToolsHooks;
-  userConfig: AppToolsUserConfig;
-  normalizedConfig: AppToolsNormalizedConfig;
-};
-```
-
-When writing plugins, plugins extend their own types like Hooks on different bases through generic extensions:
-
-```ts
-// common plugin
-import type { CliPlugin } from '@modern-js/core';
-import type { MyPluginHook } from 'xxx';
-
-const myPlugin: CliPlugin<{ hooks: MyPluginHook }> = {};
-```
-
-```ts
-// extend from app-tools hook
-import type { CliPlugin, AppTools } from '@modern-js/app-tools';
-import type { MyPluginHook } from 'xxx';
-
-const myPlugin: CliPlugin<AppTools & { hooks: MyPluginHook }> = {};
-```
-
-Please refer to [Extending Hooks](/plugin/plugin-system/extend) for detailed explanations.
-
-### Plugin Configuration
-
-**It is recommended to develop plugins in the form of functions**, so that plugins can receive configuration options through function parameters:
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-type MyPluginOptions = {
-  foo: string;
-};
-
-const myPlugin = (options: MyPluginOptions): CliPlugin => ({
-  name: 'my-plugin',
-
-  setup() {
-    console.log(options.foo);
-  },
-});
-```
-
-### Plugin API
-
-The `setup` function of a plugin receives an `api` parameter, and you can call some methods provided on the `api` to get configuration, application context, and other information.
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export const myPlugin = (): CliPlugin => ({
-  name: 'my-plugin',
-
-  setup(api) {
-    // get user set config
-    const config = api.useConfigContext();
-    // get context
-    const appContext = api.useAppContext();
-    // get final config
-    const resolvedConfig = api.useResolvedConfigContext();
-  },
-});
-```
-
-For more detail [Plugin API](/plugin/plugin-system/plugin-api).
-
-### Async setup
-
-The `setup` function of a CLI plugin can be an asynchronous function, which can execute asynchronous logic during the initialization process.
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export const myPlugin = (): CliPlugin => ({
-  name: 'my-plugin',
-
-  async setup(api) {
-    await doSomething();
-  },
-});
-```
-
-Note that the setup function of the next plugin is not executed until the async setup function of the current plugin has finished. Therefore, you should avoid performing time-consuming asynchronous operations in the setup function to avoid slowing down the startup performance of the CLI.
-
-## Adding Plugins
-
-Custom plugins can be used by following the instructions in the [plugins](/configure/app/plugins) section of the documentation. Below is the recommended way to implement plugins in Modern.js.
-
-### Developing Local Plugins
-
-It is recommended to write local plugins in the `config/plugin` directory and export them using `export default`:
-
-```ts title=config/plugin/myPlugin.ts
-import type { CliPlugin } from '@modern-js/core';
-
-export const myPlugin = (): CliPlugin => ({
-  name: 'my-plugin',
-
-  setup() {
-    // init plugin
-  },
-});
-```
-
-register plugin in `modern.config.ts`:
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-import { myPlugin } from './config/plugin/myPlugin';
-
-export default defineConfig({
-  plugins: [myPlugin()],
-});
-```
-
-### Publishing a Plugin on npm
-
-If you want to publish your Modern.js plugin on npm, it's recommended to use the [Modern.js Module](https://modernjs.dev/module-tools) to manage and build the plugin.
-
-First, create an empty Modern.js Module project and adjust the package name:
-
-```json
-{
-  "name": "my-plugin"
-  ...
-}
-```
-
-Create plugin main file:
-
-```ts title=src/index.ts
-import type { CliPlugin } from '@modern-js/core';
-
-export const myPlugin = (): CliPlugin => ({
-  name: 'my-plugin',
-
-  setup() {
-    // plugin init
-  },
-});
-```
-
-After publishing, install it to the project you need to use `pnpm add my-plugin`, take an application project as an example, and then add it in `modern.config.ts`:
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-import { myPlugin } from 'my-plugin';
-
-export default defineConfig({
-  plugins: [myPlugin()],
-});
-```
-
-If you find that there are currently unsatisfactory scenarios in Modern.js, welcome to build the Modern.js ecosystem together by **writing custom plugins**.

package/docs/en/plugin/plugin-system/introduction.mdx

@@ -1,95 +0,0 @@
----
-sidebar_position: 1
----
-
-# Introduction
-
-## Modern.js Plugin System
-
-Modern.js offers a comprehensive plugin system with a complete lifecycle. Plugins can be used to extend different stages of project operation, request handling, rendering, and more.
-
-## Usage
-
-Plugins must be explicitly registered in the configuration file to be effective. When you need to add plugins to Modern.js, you can configure them in the `[plugins](/configure/app/plugins.html)` field:
-
-```ts title="edenx.config.ts"
-// an example for bff
-import { appTools, defineConfig } from '@modern-js/app-tools';
-import { bffPlugin } from '@modern-js/plugin-bff';
-
-export default defineConfig({
-  plugins: [appTools(), bffPlugin()],
-});
-```
-
-:::note
-Note that this configuration only supports adding Modern.js plugins and does not support adding Webpack plugins.
-:::
-
-## Official Plugins
-
-Modern.js offers a range of official plugins, which are integrated with the Modern.js generator. All the functionalities of the official plugins can be enabled by executing the `new` command. For instance, to enable the BFF (Backend For Frontend) feature:
-
-```bash
-$ npx modern new
-? Please select the operation you want: Enable Features
-? Please select the feature name: (Use arrow keys)
-  Enable Tailwind CSS
-❯ Enable BFF
-  Enable SSG
-  Enable Micro Frontend
-```
-
-After the selection is completed, the Modern.js generator will automatically install the corresponding plugins and third-party dependencies. Upon completion of the installation, you will see:
-
-```bash
-[INFO] Dependency automatic installation succeeded
-
-[INFO] install plugin dependencies success！add follow code to modern.config.ts :
-
-import { bffPlugin } from '@modern-js/plugin-bff';
-import { expressPlugin } from '@modern-js/plugin-express';
-
-export default defineConfig({
-  ...,
-  plugins: [..., bffPlugin(), expressPlugin()],
-});
-```
-
-At this point, you can add the plugin to the configuration file according to the output in the console.
-
-## Composition
-
-The Modern.js plugin system is mainly divided into three parts: Hook model, Manager, and Context Sharing Mechanism.
-
-- The Hook model is used to determine the execution logic of the current Hook.
-- The Manager controls the execution and scheduling of Hooks.
-- The Context Sharing Mechanism is used to pass information between different Hooks.
-
-Currently, Modern.js offers several different Hook models: **Pipeline, Waterfall, Workflow**.
-
-:::note
-Subsequent chapters will introduce the execution methods of each model in detail.
-:::
-
-Based on the Hook model and Manager, Modern.js exposes three sets of plugins: CLI, Runtime, and Server.
-
-Among them, the CLI plugin is the main running flow control model in Modern.js, and most of the features in Modern.js are mainly run through this set of models. The Runtime plugin is mainly responsible for processing the rendering logic of React components. The Server plugin is mainly used for controlling the server lifecycle and user requests.
-
-## What Plugins Can Do
-
-All of Modern.js's features are implemented through this set of plugins, which means that all of Modern.js's capabilities are open to developers. Developers can develop plugins to extend more functionality and adapt to complex scenarios, including but not limited to:
-
-- Registering commands
-- Modifying Modern.js configuration and validation schema
-- Modifying compilation configurations for Webpack/Babel/Less/Sass/Tailwind CSS/...
-- Modifying the React components/elements to be rendered at runtime
-- Modifying page routing
-- Modifying server routing
-- Customizing console output
-- Customizing dynamic HTML templates
-- Customizing Node.js server frameworks
-- Customizing React component client/server rendering
-- ...
-
-When Modern.js does not currently cover the functionality or scenario that you need, you can develop a custom plugin to implement the related functionality for adapting to special scenarios.

package/docs/en/plugin/plugin-system/lifecycle.mdx

@@ -1,16 +0,0 @@
----
-sidebar_position: 1
----
-
-# Lifecycle
-
-Modern.js application has a complete lifecycle, including CLI, Server Side and Runtime three stages.
-
-Modern.js lifecycle is as follows:
-
-:::note
-The rectangle of the pink box represents the plugin hook provided by the Modern.js, and the light yellow base color ellipse represents the linkage point with the next stage.
-
-:::
-
-![lifecycle](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/life-cycle.svg)

package/docs/en/plugin/plugin-system/plugin-api.mdx

@@ -1,138 +0,0 @@
----
-sidebar_position: 6
----
-
-# Plugin API
-
-The `setup` function of the plugin will receive an `api` imported parameter, and you can call some methods provided on the api to obtain information such as configuration and application context.
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export const myPlugin = (): CliPlugin => ({
-  name: 'my-plugin',
-
-  setup(api) {
-    // get user config
-    const config = api.useConfigContext();
-    // get plugin context
-    const appContext = api.useAppContext();
-    // get resolved config
-    const resolvedConfig = api.useResolvedConfigContext();
-  },
-});
-```
-
-## API
-
-### useConfigContext
-
-Used to retrieve the original configuration of the application.
-
-```ts
-const useConfigContext: () => UserConfig;
-
-interface UserConfig {
-  source?: SourceConfig;
-  output?: OutputConfig;
-  server?: ServerConfig;
-  deploy?: DeployConfig;
-  // ...other fields
-}
-```
-
-Please refer to [Configuration](/configure/app/usage) for the specific meanings of configuration fields.
-
-:::tip
-This method returns a read-only configuration and cannot be modified. If you need to modify the configuration, please use [config hook](/plugin/plugin-system/hook-list.html#config).
-:::
-
-### useResolvedConfigContext
-
-Used to retrieve the final configuration after parsing.
-
-```ts
-const useResolvedConfigContext: () => NormalizedConfig;
-
-interface NormalizedConfig {
-  source: NormalizedSourceConfig;
-  output: NormalizedOutputConfig;
-  server: NormalizedServerConfig;
-  deploy: NormalizedDeployConfig;
-  _raw: UserConfig; // the original user config
-  // ...other fields
-}
-```
-
-Please refer to [Configuration](/configure/app/usage) for the specific meanings of configuration fields.
-
-:::tip
-This method returns a read-only configuration and cannot be modified. If you need to modify the configuration, please use [config hook](/plugin/plugin-system/hook-list.html#config).
-:::
-
-### useAppContext
-
-Used to retrieve the runtime context of the application.
-
-```ts
-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;
-  /** Name of the current project's package.json */
-  packageName: string;
-  /** Currently registered plugins */
-  plugins: any[];
-  /** Information for entry points */
-  entrypoints: Entrypoint[];
-  /** Information for server routes */
-  serverRoutes: ServerRoute[];
-  /** Tools type of the current project */
-  toolsType?: 'app-tools' | 'module-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.
-
-```ts
-import type { CliPlugin } from '@modern-js/core';
-
-export const myPlugin = (): CliPlugin => ({
-  name: 'my-plugin',
-
-  async setup(api) {
-    const hookRunners = api.useHookRunners();
-    // invoke afterBuild Hook
-    await hookRunners.afterBuild();
-  },
-});
-```
-
-:::tip
-Please avoid executing the built-in hooks, as it may break the internal execution logic of the framework.
-:::