@modern-js/main-doc 2.7.0 → 2.9.0

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.
+
+:::

package/docs/en/guides/topic-detail/generator/config/app.mdx

@@ -0,0 +1,82 @@
+---
+sidebar_position: 2
+---
+
+# Web App
+
+## Project creation
+
+When creating a project, the configuration used by `@modern-js/create` when using the `--config` parameter, and the configuration used when modifying and adding input in the generator plugin.
+
+The application project creation parameters are [Generator Configuration](/guides/topic-detail/generator/config/common).
+
+## New Command
+
+The new command configuration in the application project can be used through the `--config` parameter configuration when executing the new command, or when creating elements and enabling functions in the generator plugin.
+
+### actionType
+
+The action type (actionType) of the New command , the type supports two types:
+
+- element: reate engineering elements
+
+- function: enable function
+
+:::info
+This parameter is not required when using the enable function and creating elements in the generator plugin, it is automatically added in the generator plugin.
+
+:::
+
+### element
+
+Element name (element), supports two options:
+
+- Create an application entry(entry)
+
+- Create customized server dir(server)
+
+The entry also need to be used in conjunction with the specific configuration, which is described as follows:
+
+#### name
+
+Entry name (name), character `string` type.
+
+### function
+
+Optional function name (function), supports the following options:
+
+- Tailwind CSS(tailwindcss)
+
+- BFF(bff)
+
+- SSG(ssg)
+
+- Micro Frontend(micro_frontend)
+
+- Unit Test / Integration Test(test)
+
+- Storybook(mwa_storybook)
+
+- UA-based Polyfill Feature'(polyfill)
+
+- Global Proxy(proxy)
+
+`bff` also need to be used in conjunction with configuration, as described below:
+
+#### BFF parameters
+
+##### bffType
+
+BFF type (bffType), supports two options:
+
+- Function mode(function)
+
+- Framework mode(framework)
+
+##### framework
+
+BFF runtime framework (framework)，supports two options:
+
+- Express(express)
+
+- Koa(koa)

package/docs/en/guides/topic-detail/generator/plugin/api/input/addInputAfter.mdx

@@ -0,0 +1,55 @@
+---
+sidebar_position: 3
+---
+
+# addInputAfter
+
+Add input question after default input.
+
+The method is available directly on the context.
+
+Its type is defined as:
+
+```ts
+export interface IPluginContext {
+  addInputAfter: (key: string, input: Schema) => void;
+  ...
+}
+```
+
+## key
+
+Modern.js the problem keyword of the configuration of the engineering solution, the specific configuration viewable [Generator Configuration](/guides/topic-detail/generator/config/common).
+
+## input
+
+Questions that need to be added, specific type definition viewable [Customize input related type definition](/guides/topic-detail/generator/plugin/api/input/type).
+
+## Example
+
+Add input after package manager:
+
+```ts
+context.addInputAfter('packageManager', {
+  type: 'object',
+  properties: {
+    language: {
+      type: 'string',
+      title: 'Develop Language',
+      enum: [
+        { label: 'TS', value: 'ts' },
+        { label: 'ES6+', value: 'js' },
+      ],
+    },
+  },
+});
+```
+
+:::info Notes
+1. The key of the added question cannot be duplicated with the key of the question of the item type itself provided by the Modern.js.
+
+2. The priority of adding the problem `addInputAfter` is higher than `addInputBefore`. When adding After problem to one `key` and Before problem to the next key at the same time, After problem will be before Before.
+
+3. When multiple questions need to be added before or after the same `key`, the method can be called multiple times, and the order of questions will be permutated in the order in which they are called.
+
+:::

package/docs/en/guides/topic-detail/generator/plugin/api/input/addInputBefore.mdx

@@ -0,0 +1,55 @@
+---
+sidebar_position: 2
+---
+
+# addInputBefore
+
+Add input question before default input.
+
+The method is available directly on the context.
+
+Its type is defined as:
+
+```ts
+export interface IPluginContext {
+  addInputBefore: (key: string, input: Schema) => void;
+  ...
+}
+```
+
+## key
+
+Modern.js the problem keyword of the configuration of the engineering solution, the specific configuration viewable [Generator Configuration](/guides/topic-detail/generator/config/common).
+
+## input
+
+Questions that need to be added, specific type definition viewable [Customize input related type definition](/guides/topic-detail/generator/plugin/api/input/type).
+
+## Example
+
+Add input before package manager:
+
+```ts
+context.addInputBefore('packageManager', {
+  type: 'object',
+  properties: {
+    language: {
+      type: 'string',
+      title: 'Develop Langauge',
+      enum: [
+        { label: 'TS', value: 'ts' },
+        { label: 'ES6+', value: 'js' },
+      ],
+    },
+  },
+});
+```
+
+:::info Notes
+1. The key of the added question cannot be duplicated with the key of the question of the item type itself provided by the Modern.js.
+
+2. The priority of adding the problem `addInputAfter` is higher than `addInputBefore`. When adding After problem to one `key` and Before problem to the next key at the same time, After problem will be before Before.
+
+3. When multiple questions need to be added before or after the same `key`, the method can be called multiple times, and the order of questions will be permutated in the order in which they are called.
+
+:::

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

@@ -0,0 +1,18 @@
+---
+sidebar_position: 1
+---
+
+# install
+
+Install dependency in the project root directory.
+
+In the install function, the dependency will be installed using the corresponding package manager based on the value of `packageManager`.
+
+Its type is defined as:
+
+```ts
+export type AfterForgedAPI = {
+  install: () => Promise<void>;
+  ...
+};
+```

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

@@ -0,0 +1,125 @@
+---
+sidebar_position: 3
+---
+
+# How to develop generator plugins
+
+## Create project
+
+Modern.js provides a generator plugin to create a generator plugin project, you can directly execute the following command to create:
+
+```bash
+npx @modern-js/create plugin --plugin @modern-js/generator-plugin-plugin
+```
+
+Different plugin types will ask different questions. You can choose the plugin type according to your needs.
+
+### Extension type
+
+```
+? Please select the solution you want to create: Npm Module
+? Please select the scene you want to create: Generator Plugin
+? Plugin Package Name: plugin
+? Development Language: TS
+? Package Manager: pnpm
+? Plugin Type: extend
+? Plugin Base Type: Web App
+```
+
+### Customized type
+
+```
+? Plugin Package Name: plugin
+? Development Language: TS
+? Package Manager: pnpm
+? Plugin Type: custom
+? Plugin Key: mobile-app
+? Plugin Show Name: Mobile App
+? Plugin Base Type: Web App
+```
+
+After the execution of the create project command is completed, a project for developing the generator plugin will be generated accordingly, and the `meta` information will also be generated according to your selection in the `package.json`.
+
+:::info
+For generator plugin development, please refer to `@modern-js/generator-plugin-plugin`. [Source Code](https://github.com/web-infra-dev/modern.js/tree/main/packages/generator/plugins/generator-plugin)
+
+:::
+
+## Develop plugin logic
+
+Complete plugin logic development in `src/index.ts`.
+
+The plugin exports a function by default, the function parameter is `context`, and some methods are provided on `context` to directly operate on the current project.
+
+A brief introduction to the provided methods, the complete API list viewable [Generator Plugin API](/guides/topic-detail/generator/plugin/api/introduce).
+
+### Customize input
+
+- addInputBefore
+
+Add input before the default input, such as adding questions before the `Select package manager` question.
+
+Specific Modern.js configuration viewable for each problem [Project Solution Configuration](/guides/topic-detail/generator/config/common).
+
+```ts
+context.addInputBefore('input2', {
+  type: 'object',
+  properties: {
+    'input1.2': {
+      type: 'string',
+      title: 'input1.2',
+    },
+  },
+});
+```
+
+- setInput
+
+Set attributes of existing problems.
+
+```ts
+context.setInput('test', 'type', 'number');
+context.setInput('test', 'enum', [{ value: 'option1', label: '选项一' }]);
+```
+
+### onForged
+
+After the implementation of the hook related operations of the project plan type file is completed, multiple extended inspection will execute its `onForged` function in sequence according to the `plugin` parameter order.
+
+The `onForged` parameter is a callback function, and the function parameters are `api` and `input`.
+
+Some file manipulation related methods are provided on the `api`, which can operate on the current template file in this hook.
+
+`input` is the current user input, which can be used to obtain the current input information and configuration information of the user.
+
+When you need a new template file, you can add it directly in the `templates` directory. In the `onForged` function, you can directly operate the `templates` directory file. For example, the `templateFile` parameter in the `addFile` below is the file in the `templates` directory. There is no need to display the declaration `templates` here, just write the relative path relative to `templates`.
+
+API functions supported in `onForged` can also be found in [Generator Plugin API](/guides/topic-detail/generator/plugin/api/hook/onForged).
+
+```ts
+context.onForged(async (api: ForgedAPI, input: Record<string, unknown>) => {
+  const { language } = input;
+  api.addFile({
+    type: FileType.Text,
+    file: `src/index.${language as string}`,
+    templateFile: `index.${language as string}.handlebars`,
+    force: true,
+  });
+});
+```
+
+### afterForged
+
+After the `onForged` function is executed, it can mainly install dependencies, Git operations, etc.
+
+If your project plan is based on the three projects provided by the Modern.js, this hook function may not be required. The default project plan will automatically include the installation dependency and commit code logic.
+
+The generator plugin also supports a customized `custom` type, which only provides a small amount of development-level best practice code, such as `.gitignore`, `editorConfig` and other files. In this case, you need to manually supplement the installation dependency and Git operation logic in the `afterForged` function.
+
+The `afterForged` parameter is also a callback function, and the function parameters are `api` and `input`.
+
+The `api` will provide some npm, Git and other methods, which can install dependency and Git operations in this hook.
+
+`input` is the current user input, which can be used to obtain the current input information and configuration information of the user.
+
+The API functions supported in `afterForged` can also be found in [Generator Plugin API](/guides/topic-detail/generator/plugin/api/hook/afterForged).

package/docs/en/guides/topic-detail/generator/project.mdx

@@ -0,0 +1,118 @@
+---
+sidebar_position: 2
+---
+
+# Project Generator
+
+Modern.js provides `@modern-js/create` as a project generator for Modern.js project creation.
+
+## Use
+
+There is no need to install `@modern-js/create` globally, just execute the tool directly with npx:
+
+```bash
+npx @modern-js/create [projectDir]
+```
+
+:::info
+Use npx to get the latest version of `@modern-js/create` every time.
+
+:::
+
+## Params
+
+### [projectDir]
+
+Project directory name.
+
+When executing the above command, the `projectDir` folder will be created in the current directory by default, and the initialization project will be in this folder. When this parameter is empty, the initialization project will be directly generated in the current directory.
+
+### --version
+
+Get the `@modern-js/create` tool version.
+
+```bash
+$ npx @modern-js/create --version
+
+[INFO] @modern-js/create v2.0.0
+```
+
+### --lang
+
+Specifies the execution language, supports `zh` and `en`.
+
+By default, `@modern-js/create` will automatically identify the user's system language, choose to use Chinese or English, if the recognition fails or you want to specify the language manually, you can use this parameter.
+
+### -c, --config
+
+Specifies the project default configuration.
+
+By default, `@modern-js/create` will have interaction problems such as language selection and package managers during execution. When you need to specify these configuration contents in advance, you can pass in this field.
+
+This field is a JSON character string, for example when running a package manager:
+
+```bash
+npx @modern-js/create --config '{"packageManager": "pnpm"}'
+```
+
+Specific configuration information viewable [Project Configuration](/guides/topic-detail/generator/config/common).
+
+### --no-need-install
+
+By default, `@modern-js/create` automatically installs dependency after the project is created, use this parameter to ignore the install dependency step.
+
+### --dist-tag \<distTag\>
+
+Specifies the generator and Modern.js dependency versions.
+
+A smaller micro-generator will be executed during the execution of `@modern-js/create`, and the version number of the micro-generator that can be executed with this parameter and the version number of the corresponding installation Modern.js related dependencies.
+
+### --registry \<registry/>
+
+Execute the npm registry to get the generator and npm packages.
+
+### --debug
+
+Displays debug log information during generator execution.
+
+### --mwa
+
+One-click to create an application engineering solution project.
+
+With this parameter, `@modern-js/create` will create the application project with the configuration default value.
+
+### --module
+
+One-click to create a module engineering solution project.
+
+With this parameter, `@modern-js/create` will create the module project with the configuration default value.
+
+### --monorepo
+
+One-click to create a Monorepo engineering solution project.
+
+With this parameter, `@modern-js/create` will create the Monorepo project with the configuration default value.
+
+### --plugin \<plugin\>
+
+Specifies the generator plugin.
+
+Modern.js support the use of the generator plug-in custom Modern.js the default project type or add the project type scenes, the parameter user specifies the customized generator plugin.
+
+For custom generator plugins, please refer to [Development Generator Plugin](/guides/topic-detail/generator/plugin/abstract).
+
+### --generator \<generator\>
+
+Specifies the microgenerator.
+
+By default, `@modern-js/create` will execute the microgenerator Modern.js framework build-in. If you need to execute a customized microgenerator, and you need to use the posture of `npx @modern-js/create`, you can use this parameter directly.
+
+For custom microgenerators, please refer to [Develop Microgenerator](/guides/topic-detail/generator/codesmith/introduce).
+
+### --packages \<packages\>
+
+A project is created by specifying a specific package version dependency.
+
+If you need to specify a specific package version when creating a project, you can use this parameter. This parameter will lock the package version number in the `package.json` of the project root directory by configuration `pnpm.overrides` (package manager selects pnpm) or `resolutions`.
+
+The parameter value is a JSON character string.