@modern-js/main-doc 0.0.0-nightly-20241104170657 → 0.0.0-nightly-20241106064312

package/docs/en/guides/topic-detail/generator/plugin/_meta.json

@@ -1,11 +0,0 @@
-[
-  "structure",
-  "category",
-  "use",
-  "context",
-  {
-    "type": "dir",
-    "name": "api",
-    "label": "API"
-  }
-]

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

@@ -1,49 +0,0 @@
----
-sidebar_position: 3
----
-
-# afterForged
-
-`afterForged` is a lifecycle function used for other step operations after file operations in generator plugin.
-
-## Types
-
-```ts
-export type AfterForgedAPI = {
-  isInGitRepo: () => Promise<boolean>;
-  initGitRepo: () => Promise<void>;
-  gitAddAndCommit: (commitMessage: string) => Promise<void>;
-  install: () => Promise<void>;
-};
-
-export type PluginAfterForgedFunc = (api: AfterForgedAPI, inputData: Record<string, unknown>) => Promise<void>;
-
-export interface IPluginContext {
-   afterForged: (func: PluginAfterForgedFunc) => void;
-  ...
-}
-```
-
-## API
-
-The APIs provided by the `api` parameter will be introduced below.
-
-### isInGitRepo
-
-Checks whether the current project is a git repository.
-
-### initGitRepo
-
-Initializes the current project as a git repository.
-
-### gitAddAndCommit
-
-Commits changes to the current repository.
-
-Parameters:
-
-- `commitMessage`: commit message.
-
-### install
-
-Installs dependencies in the root directory of the project. The `install` function will use the corresponding package manager according to the value of `packageManager` to install dependencies.

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