@modern-js/main-doc 2.60.5 → 2.61.0

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

@@ -1,184 +0,0 @@
----
-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

@@ -1,124 +0,0 @@
----
-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

@@ -1,310 +0,0 @@
----
-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 `modernConfig` 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

@@ -1,88 +0,0 @@
----
-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
-```
-
-### Custom
-
-```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.