@modern-js/main-doc 2.21.1 → 2.22.1

package/docs/en/guides/topic-detail/generator/plugin/api/context.md

@@ -0,0 +1,184 @@
+---
+sidebar_position: 1
+---
+
+# context
+
+The generator plugin exports a function by default in the `main` file, and the function parameter is `context`. All APIs provided by the generator plugin are provided by this `context`.
+
+## Types
+
+Let's first understand the type definition of `context`:
+
+```ts
+export interface IPluginContext {
+  locale?: string;
+  addInputBefore: (key: string, input: Schema) => void;
+  addInputAfter: (key: string, input: Schema) => void;
+  setInput: (key: string, field: string, value: unknown) => void;
+  setInputValue: (value: Record<string, unknown>) => void;
+  setDefaultConfig: (value: Record<string, unknown>) => void;
+  isFileExist: (fileName: string) => Promise<boolean>;
+  readDir: (dir: string) => Promise<string[]>;
+  setGitMessage: (gitMessage: string) => void;
+  onForged: (func: PluginForgedFunc) => void;
+  afterForged: (func: PluginAfterForgedFunc) => void;
+}
+```
+
+The contents provided by `context` can be mainly divided into three categories:
+
+- Get the information of the current generator execution environment.
+
+- Operate input.
+
+- Generator plugin lifecycle function.
+
+
+The generator plugin APIs will be introduced from these three categories below.
+
+### Get Information
+
+#### locale
+
+Gets the language of the generator plugin execution environment. `@modern-js/create` provides two languages, `zh` and `en`, which correspond to these two values.
+
+#### isFileExist
+
+Checks whether a file exists. We often need to confirm whether the target project file exists before defining the operation. This API can be used directly for this purpose.
+
+For example, we need to find out if the `package.json` file exists and then do someing:
+
+```ts
+const isExist = await context.isFileExist('package.json');
+if (isExist) {
+    ...
+}
+```
+
+#### readDir
+
+Gets the file list in a folder. We often need to get the file list under the target project folder before defining the operation. This API can be used directly for this purpose.
+
+For example, we need to get all files under the `src` folder and then do someing:
+
+```ts
+const files = await context.readDir('src');
+
+files.map(name => {
+    ...
+});
+```
+
+### Input Operations
+
+The `key` parameter used in input operations can refer to [Configuration Parameters](/guides/topic-detail/generator/create/config.html) and use the key under the solution’s scheme, that is, it does not support `solution` and `scenes`.
+
+The input parameter in input operations corresponds to the schema type described in [Input](/guides/topic-detail/generator/plugin/api/input.html).
+
+#### addInputBefore
+
+Adds a question before the specified input `key`.
+
+For example:
+
+```ts
+context.addInputBefore('packageManager', {
+  type: 'object',
+  properties: {
+    language: {
+      type: 'string',
+      title: 'Please select the programming language:',
+      enum: [
+        { label: 'TS', value: 'ts' },
+        { label: 'ES6+', value: 'js' },
+      ],
+    },
+  },
+});
+```
+
+#### addInputAfter
+
+Adds a question after the specified input `key`.
+
+For example:
+
+```ts
+context.addInputAfter('packageManager', {
+  type: 'object',
+  properties: {
+    language: {
+      type: 'string',
+      title: 'Please select the programming language:',
+      enum: [
+        { label: 'TS', value: 'ts' },
+        { label: 'ES6+', value: 'js' },
+      ],
+    },
+  },
+});
+```
+
+:::info
+1. The `key` for adding a question cannot be the same as the `key` of the question provided by Modern.js solution scheme itself.
+2. The priority of adding a question with `addInputAfter` is higher than that of `addInputBefore`. When adding an After question to a key and adding a Before question to the next key, the After question will be before the Before question.
+3. When adding multiple questions before or after the same `key`, this method can be called multiple times, and the order of the questions will be arranged according to the calling sequence.
+
+:::
+
+#### setInput
+
+Sets the attributes of the specified input `key`.
+
+For example, set the `title` attribute of `packageName`:
+
+```ts
+context.setInput('packageName', 'title', "Name");
+```
+
+:::info
+For input options provided by Modern.js solution schemes, only deletion is supported, and adding will cause logical judgment problems in the code.
+:::
+
+
+#### setInputValue
+
+Sets the default value of the specified input `key`.
+
+For example, set the default value of `packageManager`:
+
+```ts
+context.setInputValue({
+  packageManager: 'npm',
+});
+```
+
+:::info
+After setting, the question still needs to be interactive, but the default value configured by the generator plugin will be used.
+:::
+
+#### setDefaultConfig
+
+Sets the default value of the specified input `key`.
+
+For example, set the default value of `packageManager`:
+
+```ts
+context.setDefaultConfig({
+  packageManager: 'npm',
+});
+```
+
+:::info
+After setting, the corresponding question will no longer be displayed, which is consistent with the `--config` behavior specified by `@modern-js/create`. Does not support setting `vertical` and `projectOrg`.
+:::
+
+#### setGitMessage
+
+Sets the initial git commit message. Modern.js defaults to the git initialization commit message as `feat: init`, which can be modified by this function.
+
+
+### Lifecycle Functions
+
+The lifecycle functions are relatively complex and will be introduced separately in the following two sections, [`onForged`](/guides/topic-detail/generator/plugin/api/onForged.html) and [`afterForged`](/guides/topic-detail/generator/plugin/api/afterForged.html).

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

@@ -0,0 +1,124 @@
+---
+sidebar_position: 4
+---
+
+# Input
+
+Generator plugin provides a way to interact with users through Input, which is defined using JSON Schema:
+
+For example:
+
+```js
+const schema = {
+  type: 'object',
+  properties: {
+    language: {
+      type: 'string',
+      title: 'Please select the programming language:',
+      enum: [
+        { label: 'TS', value: 'ts' },
+        { label: 'ES6+', value: 'js' },
+      ],
+    },
+  },
+};
+```
+
+JSON Schema format is based on the open source [Formily](https://formilyjs.org/) Schema format. The following are the supported fields:
+
+## type
+
+Defines the type of the current schema. Currently supported types are `string`, `number`, and `object`. `string` type is used for string inputs and dropdown options. `object` type is used for nesting schemas and needs to be used with the `properties` attribute.
+
+## title
+
+Defines the display name of the current schema.
+
+## default
+
+Defines the default value of the current schema.
+
+## enum
+
+Defines the options when the current schema is a dropdown selection.
+
+The sub-items support `string` or `{ label: string; value: string}` types. When the value and display value are the same in the dropdown options, `string` can be used directly to define the options.
+
+When representing multiple selection options, set the `default` field to `[]`.
+
+## x-validator
+
+Defines the validation rules for the current schema. When the schema is an input type, validation will be automatically performed after input completion.
+
+The validation rules supported here are provided by [Formily](https://formilyjs.org/zh-CN/guide/advanced/validate), for example, the maximum value is 5:
+
+```js
+const schema = {
+  type: 'object',
+  properties: {
+    max_5: {
+      type: 'number',
+      title: 'Maximum value (>5 will cause an error)',
+      'x-validator': {
+        maximum: 5,
+      },
+    },
+  },
+};
+```
+
+It also supports using validation functions directly:
+
+```js
+const schema = {
+  type: 'object',
+  properties: {
+    path: {
+      type: 'string',
+      title: 'Can only contain numbers and letters',
+      'x-validator': value => {
+        if (!/^[0-9a-zA-Z]*$/g.test(value)) {
+          return 'Incorrect format';
+        }
+        return '';
+      },
+    },
+  },
+};
+```
+
+## x-reactions
+
+Use linkage between schemas. This is exactly the same as [Formily linkage rules](https://formilyjs.org/zh-CN/guide/advanced/linkages).
+
+For example:
+
+```js
+const schema = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      title: 'Name',
+    },
+    path: {
+      type: 'string',
+      title: 'Path',
+      'x-reactions': [
+        {
+          dependencies: ['name'],
+          fulfill: {
+            state: {
+              value: '{{$deps[0]}}',
+            },
+          },
+        },
+      ],
+    },
+  },
+};
+```
+
+## properties
+
+Organize the structure of the current schema and define sub-forms. `properties` is an object, where the `key` is the schema keyword and the `value` is a schema object as described above.

package/docs/en/guides/topic-detail/generator/plugin/api/onForged.md

@@ -0,0 +1,310 @@
+---
+sidebar_position: 2
+---
+
+# onForged
+
+`onForged` is a lifecycle function used for file operations in generator plugin.
+
+## Types
+
+```ts
+export type ForgedAPI = {
+  addFile: (params: AddFileParams) => Promise<void>;
+  addManyFiles: (params: AddManyFilesParams) => Promise<void>;
+  updateJSONFile: (fileName: string, updateInfo: Record<string, unknown>) => Promise<void>;
+  updateTextRawFile: (fileName: string, update: (content: string[]) => string[]) => Promise<void>;
+  updateModernConfig: (updateInfo: Record<string, any>) => Promise<void>;
+  rmFile: (fileName: string) => Promise<void>;
+  rmDir: (dirName: string) => Promise<void>;
+  addHelper: (name: string, fn: Handlebars.HelperDelegate) => void;
+  addPartial: (name: string, str: Handlebars.Template) => void;
+  createElement: (element: ActionElement, params: Record<string, unknown>) => Promise<void>;
+  enableFunc: (func: ActionFunction, params?: Record<string, unknown> | undefined) => Promise<void>;
+};
+
+export type PluginForgedFunc = (
+  api: ForgedAPI,
+  inputData: Record<string, unknown>,
+) => void | Promise<void>;
+
+export interface IPluginContext {
+  onForged: (func: PluginForgedFunc) => void;
+  ...
+}
+```
+
+The `onForged` parameter is a callback function with `api` and `input` as parameters, which are used to provide the APIs and current input information provided by the lifecycle function.
+
+## Concepts
+
+### File Types
+
+The generator plugin classifies files into four categories:
+
+- Text files
+
+Files with pure text content that can be processed using [Handlebars](https://handlebarsjs.com/) or [EJS](https://ejs.co/) templates.
+
+- Binary files
+
+Files such as images, audio, and video.
+
+- JSON files
+
+Files in JSON format.
+
+- Text list files
+
+Files composed of lines of text, such as `.gitignore`, `.editorconfig`, and `.npmrc`.
+
+The type definitions for the four types of files are:
+
+```ts
+export enum FileType {
+  Text = 'text',
+  Binary = 'binary',
+  Json = 'json',
+  TextRaw = 'textRaw',
+}
+```
+
+## API
+
+The APIs provided by the `api` parameter will be introduced below.
+
+### addFile
+
+Adds a single file.
+
+Parameter types:
+
+```ts
+export interface AddFileParams {
+  type: FileType;
+  file: string;
+  template?: string;
+  templateFile?: string;
+  force?: boolean;
+  data?: Record<string, string>;
+}
+```
+
+- `type`: File type.
+- `file`: Target file path, relative to the target project directory.
+- `template`: Template content, the value of this field can be directly used to render the file. Lower priority than `templateFile`.
+- `templateFile`: Template file path, relative to the templates directory.
+- `force`: Whether to force overwrite when the target file exists, default is false.
+- `data`: Template rendering data.
+
+:::info
+Text files are processed using Handlebars by default. If the template file ends with `.ejs`, [EJS](https://ejs.co/) will be used for template rendering.
+:::
+
+For example, add the template file `App.tsx.hanlebars` to `src/App.tsx`:
+
+```ts
+context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
+  await api.addFile({
+    type: FileType.Text,
+    file: `src/App.tsx`,
+    templateFile: `App.tsx.handlebars`,
+  });
+})
+```
+
+### addManyFiles
+
+Adds multiple files, usually used to add multiple files to the same target directory.
+
+Parameter types:
+
+```ts
+export interface AddManyFilesParams {
+  type: FileType;
+  destination: string;
+  templateFiles: string[] | (() => string[]);
+  templateBase?: string;
+  fileNameFunc?: (name: string) => string;
+  data?: Record<string, string>;
+}
+```
+
+- `type`: File type.
+- `destination`: Target folder, relative path to the target project directory.
+- `templateFiles`: Template file list, supporting regular expressions from [globby](https://www.npmjs.com/package/globby).
+- `templateBase`: Common path of template files. When using this parameter, the target file will automatically delete this path.
+- `fileNameFunc`: Function to rename files. During the file addition process, the file name will be passed to this function in turn, and the renaming can be performed as needed.
+- `data`: Template rendering data.
+
+For example, render all files in the `src-ts` directory of the template file to the `src` directory:
+
+```ts
+context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
+  await api.addManyFiles({
+    type: FileType.Text,
+    destination: 'src',
+    templateFiles: ['src-ts/**/*'],
+    templateBase: 'src-ts',
+    fileNameFunc: name => name.replace('.handlebars', ''),
+  });
+})
+```
+
+### updateJSONFile
+
+Update fields in a JSON file.
+
+Parameter types:
+
+```ts
+fileName: strings
+updateInfo: Record<string, unknown>
+```
+
+- `fileName`: JSON file path, relative to the target project path.
+- `updateInfo`: Update information. Nested field updates need to be flattened, otherwise the entire update will cause content loss.
+
+For example, update the `name` field of `package.json`:
+
+```ts
+context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
+  await api.updateJSONFile('package.json', { name: 'new_name' });
+})
+```
+
+For example, update the version of `react-dom` in `dependencies`:
+
+```ts
+context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
+  await api.updateJSONFile('package.json', {
+    'dependencies.react-dom': '^18',
+  });
+})
+```
+
+### updateTextRawFile
+
+Update the contents of a text list file.
+
+Parameter types:
+
+```ts
+fileName: string
+update: (content: string[]) => string[]
+```
+
+- `fileName`: Text list file path, relative to the target project path.
+- `update`: Update function. The parameter is an array divided by `\n` of the current file content, and the return value is also the modified array after modification. `@modern-js/create` will automatically merge it with `\n` and write it to the source file.
+
+For example, add the `dist` directory to the `.gitinore` file:
+
+```ts
+context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
+  await api.updateTextRawFile('.gitinore', (content) => [...content, 'dist']);
+})
+```
+
+### updateModernConfig (not recommended)
+
+In addition to configuring in `modern.config.[tj]s`, Modern.js configuration also supports configuring `modernConfig` in `package.json`. This function is used to update this field.
+
+Parameter types:
+
+```ts
+updateInfo: Record<string, any>
+```
+
+- `updateInfo`: Update content information. `updateModernConfig` is a package based on `updateJSONFile`, which will automatically update under the `edenxConfig` field. Only the configuration fields under `modernConfig` need to be filled in `updateInfo`.
+
+For example, enable SSR:
+
+```ts
+context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
+  await api.updateModernConfig({ 'server.ssr': true });
+})
+```
+
+### rmFile
+
+Delete files.
+
+Parameter types:
+
+```ts
+fileName: string
+```
+
+- `fileName`: The path of the file to be deleted, relative to the target project path.
+
+### rmDir
+
+Delete a folder.
+
+Parameter types:
+
+```ts
+dirName: string
+```
+
+- `dirName`: The path of the folder to be deleted, relative to the target project path.
+
+### addHelper
+
+Add a [custom helper](https://handlebarsjs.com/guide/#custom-helpers) rendered by handlebrs.
+
+Parameter types:
+
+```ts
+name: string
+fn: Handlebars.HelperDelegate
+```
+
+- `name`: Helper function name.
+- `fn`: Helper function implementation.
+
+### addPartial
+
+Add a [Partial](https://handlebarsjs.com/guide/partials.html#basic-partials) rendered by Handlebars.
+
+Parameter types:
+
+```ts
+name: string
+str: Handlebars.Template
+```
+
+- `name`: Partial name.
+- `str`: Template string of the Partial.
+
+### createElement
+
+Automatically run the `new` command to create project elements.
+
+Parameter types:
+
+```ts
+element: ActionElement
+params: Record<string, unknown>
+```
+
+- `element`: Type of project element, new entry or new custom Web Server source directory.
+- `params`: Other parameters corresponding to creating project elements.
+
+### enableFunc
+
+Automatically run the `new` command to enable optional features.
+
+Parameter types:
+
+```ts
+func: ActionFunction
+params?: Record<string, unknown>
+```
+
+- `func`: Name of the feature to enable.
+- `params`: Other parameters corresponding to enabling the feature.
+
+:::info
+Refer to [Configuration Parameters](/guides/topic-detail/generator/new/config.html) for creating project elements and enabling feature configurations.
+:::

package/docs/en/guides/topic-detail/generator/plugin/category.md

@@ -0,0 +1,88 @@
+---
+sidebar_position: 2
+---
+
+## Introduction
+
+There are two types of generator plugin:
+
+- Extension: Web App(Npm Module) = Web App(Npm Module) + Generator Plugin
+
+- Custom: New Application(Npm Module) = Web App(Npm Module) + Generator Plugin
+
+
+In simpler terms, extension means using the original project name of Modern.js, while custom means creating a new name.
+
+## Identifier
+
+The type of generator plugin is provided through the `meta` field in `package.json`:
+
+### Extension
+
+```json title="package.json"
+{
+ "meta": {
+    "extend": "mwa" // module
+ }
+}
+```
+
+### Custom
+
+```json title="package.json"
+{
+ "meta": {
+    "key": "new_app",
+    "name": "new App",
+    "type": "mwa" // module and custom
+ }
+}
+```
+
+:::info
+For custom type, the `type` field supports the `custom` value, which utilizes some best practice templates for project development provided by Modern.js, such as `.gitignore`, `.editorConfig`, etc. Other business-related code templates need to be manually provided through generator plugin.
+:::
+
+# Creating Initial Project
+
+### Extension
+
+```bash
+npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
+? Please select the type of project you want to create: Npm Module
+? Please select the project scenario: Generator Plugin
+? Please fill in the package name of the generator plugin: plugin
+? Please select the programming language: TS
+? Please select the package manager: pnpm
+? Please select the type of plugin: extend
+? Please select the base type of the plugin: Web App
+```
+
+### 自定义
+
+```bash
+npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
+? Please select the type of project you want to create: Npm Module
+? Please select the project scenario: Generator Plugin
+? Please fill in the package name of the generator plugin: plugin
+? Please select the programming language: TS
+? Please select the package manager: pnpm
+? Please select the type of plugin: custom
+? Please fill in the plugin keyword: new_app
+? Please fill in the display name of the plugin: new App
+? Please select the base type of the plugin: Web App
+```
+
+## Execution Order
+
+Generator plugins support using multiple plugins at the same time, which means that multiple `--plugin` parameters are supported when executing `@modern-js/create`.
+
+### Extension
+
+For extension generator plugins, when executing with the declared generator plugin parameters, the corresponding lifecycle functions of the project scheme that is extended will be executed in order.
+
+For example, if there are two generator plugins A and B, both of which extend the Modern.js application scheme. A plugin declares to add the `a.ts` file, and B plugin declares to add the `b.ts` file. When executing `npx @modern-js/create@latest --plugin A --plugin B`, and selecting the Web APP scheme, the default project files of the Web APP will be generated first. Then, the A plugin will create the `a.ts` file, and then the B plugin will generate the `b.ts` file.
+
+### Custom
+
+For custom generator plugins, only one plugin can be executed at a time. When declaring the `--plugin` parameter for `@modern-js/create`, a selection option for the scenario of choosing the project scheme will be added after selecting the project scheme, which is the new name defined in the `package.json`. Choosing the corresponding generator plugin for the name will execute the corresponding generator plugin logic after the default project scheme is completed. When declaring the `--plugin` parameter, the corresponding generator plugin names will be listed one by one for selection in the project scheme scenario.