@modern-js/main-doc 2.8.0 → 2.9.0

package/docs/en/guides/topic-detail/framework-plugin/hook.mdx

@@ -0,0 +1,188 @@
+---
+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.
+
+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. 执行
+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. 执行
+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/guides/topic-detail/framework-plugin/implement.mdx

@@ -0,0 +1,246 @@
+---
+title: Write Plugins
+sidebar_position: 3
+---
+# How to Write Plugins
+
+The previous section introduced the Hook models used by Modern.js plugins, while this section describes how to write 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](/guides/topic-detail/framework-plugin/relationship).
+
+### Plugin Types
+
+Modern.js supports various types of project development, such as application development (`app-tools`), module development (`module-tools`), 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](/guides/topic-detail/framework-plugin/extend) for detailed explanations.
+
+### Plugin Configuration
+
+**It is recommended to write 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 default (): 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](/guides/topic-detail/framework-plugin/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 default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  async setup(api) {
+    await doSomething();
+  },
+});
+```
+
+## 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 default (): 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 module project solution provided by Modern.js to manage and build the plugin.
+
+First, create an empty module project solution 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 default (): 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/guides/topic-detail/framework-plugin/relationship.mdx

@@ -0,0 +1,119 @@
+---
+title: Relationship
+sidebar_position: 4
+---
+# Relationship between Plugins
+
+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:
+
+- `name`: `string`, sets the name of the current plugin.
+- `pre`: `string[]`, these plugins will be adjusted to be executed before the current plugin.
+- `post`: `string[]`, these plugins will be adjusted to be executed after the current plugin.
+- `rivals`: `string[]`, mutually exclusive plugins, an error will be thrown when encountering these plugins.
+- `required`: `string[]`, required plugins, an error will be thrown when the corresponding plugin is not found in the plugin list.
+- `usePlugin`: `CliPlugin[]`, registers other plugins.
+
+The above parameters can be used to achieve plugin front, back, mutual exclusion, and mandatory logic.
+
+## Plugin Sorting
+
+Modern.js plugins achieve plugin sorting functionality through the `pre` and `post` parameters.
+
+### Pre
+
+By default, plugins are executed in the order they are added. You can declare preceding plugins to be executed by using the `pre` field.
+
+For example, there are the following two plugins:
+
+```ts title=foo.ts
+const foo = {
+  name: 'plugin-foo',
+};
+```
+
+```ts title=bar.ts
+const bar = {
+  name: 'plugin-bar',
+  pre: ['plugin-foo'],
+};
+```
+
+The `bar` plugin configures the `foo` plugin in the `pre` field, so the'foo' plugin must be executed before the `bar` plugin.
+
+### Post
+
+Declare succeeding plugins to be executed by using the `post` field.
+
+```ts title=foo.ts
+const foo = {
+  name: 'plugin-foo',
+};
+```
+
+```ts title=bar.ts
+const bar = {
+  name: 'plugin-bar',
+  post: ['plugin-foo'],
+};
+```
+
+If you use the `post` parameter in the `bar` plugin's configuration and set it to `['foo']`, then the `foo` plugin will be executed after the `bar` plugin.
+
+## rivals
+
+The rivals field can be used to declare a mutual exclusion relationship between plugins.
+
+there are two plugin:
+
+```ts title=foo.ts
+const foo = {
+  name: 'plugin-foo',
+};
+```
+
+```ts title=bar.ts
+const bar = {
+  name: 'plugin-bar',
+  rivals: ['plugin-foo'],
+};
+```
+
+The `bar` plugin has been configured with the `foo` plugin in the `rivals` field, therefore an error will be thrown if both the `foo` and `bar` plugins are added simultaneously.
+
+## required
+
+The `required` field can be used to declare a dependency relationship between plugins.
+
+there are two plugin:
+
+```ts title=foo.ts
+const foo = {
+  name: 'plugin-foo',
+};
+```
+
+```ts title=bar.ts
+const bar = {
+  name: 'plugin-bar',
+  required: ['plugin-foo'],
+};
+```
+
+The `bar` plugin has been configured with the `foo` plugin in the `required` field. Therefore, an error will be thrown when using the `bar` plugin if the `foo` plugin is not configured.
+
+## Register Plugin
+
+When there is a dependency relationship between plugins, we can also actively register another plugin in a plugin by using `usePlugin`.
+
+```ts title=foo.ts
+const foo = () => ({
+  name: 'plugin-foo',
+});
+
+const bar = () => ({
+  name: 'plugin-bar',
+  usePlugin: [foo()],
+});
+```
+
+When the user configures the `bar` plugin, the foo plugin will also be automatically registered and activated. The user does not need to register the `foo` plugin separately.

package/docs/en/guides/topic-detail/generator/codesmith/api/npm.mdx

@@ -0,0 +1,48 @@
+---
+sidebar_position: 7
+---
+
+# @modern-js/codesmith-api-npm
+
+The NPM API encapsulation in the microgenerator provides a common method for installing dependencies of different NPM package managers.
+
+## Use
+
+```ts
+import { NpmAPI } from '@modern-js/codesmith-api-npm';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const npmApi = new NpmAPI(generator);
+  await npmApi.pnpmInstall();
+};
+```
+
+- Create NpmAPI instance, the parameter is the generator of the microgenerator function parameter, please see the composition of the microgenerator project for details.
+
+- Just call the API on its example.
+
+## API
+
+### npmInstall
+
+Install dependency using npm.
+
+Parameter:
+
+- cwd?: `string`. The execution directory of the install command, the default is microgenerator `outputPath`.
+
+### yarnInstall
+
+Install dependency using yarn.
+
+Parameter:
+
+- cwd?: `string`. The execution directory of the install command, the default is microgenerator `outputPath`.
+
+### pnpmInstall
+
+Install dependency using pnpm.
+
+Parameter:
+
+- cwd?: `string`. The execution directory of the install command, the default is microgenerator `outputPath`.

package/docs/en/guides/topic-detail/generator/codesmith/develop.mdx

@@ -0,0 +1,53 @@
+---
+sidebar_position: 3
+---
+
+# Develop a microgenerator project
+
+## Create project
+
+Modern.js provides a microgenerator to create a microgenerator project, you can directly create a microgenerator project with the following commands:
+
+```bash
+$ mkdir <projectDir>
+$ npx @modern-js/codesmith-cli @modern-js/generator-generator
+
+? Package Name: <generatorName>
+? Package Manager: pnpm
+? Development Language: TS
+```
+
+## Add template file
+
+In the templates folder of the project directory, it is used to store the template files required by the generator. If there is no template file, this step can be skipped.
+
+## Develop generator core logic
+
+In the project generated by default, it has been implemented to directly copy the templates directory file to the target project, and the core logic development of the generator can be completed directly in the `handleTemplateFile` function.
+
+## Test microgenerator
+
+After the development of the microgenerator is completed, you need to execute `pnpm run build` to compile the code. In development mode, you can use `pnpm run build --watch`.
+
+Codesmith provides the cli tool for running and testing the microgenerator. Execute it in the target directory with the following command:
+
+```bash
+npx @modern-js/codesmith-cli <generatorPath>
+```
+
+Where `generatorPath` is the absolute path of the above generator project.
+
+## Run the microgenerator
+
+After the generator publishes to npm, use the following command to execute:
+
+```bash
+npx @modern-js/codesmith-cli <generatorName>
+```
+
+Where generatorName is the generator package name.
+
+:::info
+`@modern-js/create` also supports running micro-generators, you can use `npx @modern-js/create --generator <generatorName>` to run customized micro-generators.
+
+:::