@modern-js/main-doc 2.21.0 → 2.22.0

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

@@ -1,152 +0,0 @@
----
-sidebar_position: 1
----
-
-# @modern-js/codesmith-api-app
-
-The combination encapsulation of APIs commonly used in the development of microgenerators, including APIs encapsulation of other packages such as fs, git, npm, etc. When the requirements can be met, it is recommended to use the API of the npm package.
-
-## Use
-
-```ts
-import { AppAPI } from '@modern-js/codesmith-api-app';
-
-export default async (context: GeneratorContext, generator: GeneratorCore) => {
-  const appApi = new AppAPI(context, generator);
-  await appApi.runInstall();
-};
-```
-
-- Create AppAPI 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
-
-### checkEnvironment
-
-Check the current generator operating environment, the check items are:
-
-1. The node and node versions, the default is greater than 12.22.12, and the node version can be executed by passing parameters.
-2. Yarn, pnpm or npm can be used.
-
-Parameter:
-
-- nodeVersion?: `string`. Node version want to check.
-
-### runInstall
-
-To install dependency, you can pass in the install dependency command, which defaults to the `packageManager` value in config.
-
-Parameter:
-
-- command?: `string`, Install dependency command.
-
-### runGitAndInstall
-
-This function performs the following actions:
-
-1. Check whether the current generator execution directory is a git repository.
-2. If not a git repository, initialization is a git repository.
-3. Install dependencies.
-4. Commit the initial commit in a non-monorepo project (judging the condition, `isMonorepoSubProject` does not exist or is false in the config), the commit information is feat: init, and customize is supported.
-
-Parameter:
-
-- commitMessage?: `string`, Initialization commit message
-- installFunc?: `() => Promise<void>`. Install dependency function
-
-### forgeTemplate
-
-Render generator template file.
-
-Parameter:
-
-- templatePattern: `string`. Template files match regularities,for example: `templates/base-templates/**/*` .
-- filter?: `(resourceKey: string) => boolean`. Filter function, the parameter is the file path matching the `templatePattern`, return true to render the file, return false to render the file.
-- rename?: `(resourceKey: string) => string`. Rename function, the parameter is the file path matching `templatePattern`, and the new filename is returned. The templates directory at the beginning of `resourceKey` and the `.handlebars` suffix at the end will be replaced by default.
-- parameters?: `Record<string, any>`. Render parameter, when there is a handlebars or ejs variable in the template, use it to pass the corresponding variable value.
-- type?: `'handlebars' | 'ejs'`. Template file type, defaults to handlebars.
-
-For example:
-
-```ts
-await appApi.forgeTemplate(
-  'templates/base-templates/**/*',
-  undefined,
-  resourceKey =>
-    resourceKey
-      .replace('templates/base-templates/', '')
-      .replace('.handlebars', ''),
-);
-
-await appApi.forgeTemplate(
-  'templates/base-template/**/*',
-  resourceKey => !resourceKey.include('eslintrc.json'),
-  resourceKey =>
-    resourceKey
-      .replace('templates/base-template/', projectPath)
-      .replace('language', language as string)
-      .replace('.handlebars', ''),
-  {
-    name: packageName as string,
-    language,
-    isTs: language === Language.TS,
-    packageManager: getPackageManagerText(packageManager as any),
-  },
-);
-```
-
-### showSuccessInfo
-
-Display success information.
-
-Parameter:
-
-- successInfo?: `string`. Default is Success.
-
-### runSubGenerator
-
-Run the subgenerator.
-
-Parameter:
-
-- subGenerator: `string`. Subgenerator name or path.
-- relativePwdPath?: `string`. The relative path to which the'string 'subgenerator runs.
-- config?: `Record<string, unknown>`. Default config configuration for subgenerator runs.
-
-For example:
-
-```ts
-await appApi.runSubGenerator(
-  getGeneratorPath('@modern-js/repo-generator', context.config.distTag),
-  undefined,
-  { ...context.config, hasPlugin: false },
-);
-```
-
-### getInputBySchema
-
-User interaction input is done through schema.
-
-Parameter:
-
-- schema: `FormilySchema | Question[]`. Question list, supports Formily schema and inquirer types.
-- type: `'formily' | 'inquirer'`. Schema type, the default value is formily.
-- configValue: `Record<string, unknown> = {}`. Schema default value, the problem corresponding to the schema field passed in this value will no longer interact with the user.
-- validateMap?: `Record<string, (input: unknown, data?: Record<string, unknown>) => { success: boolean; error?: string }>`. Validation function for special fields in schema.
-- initValue?: `Record<string, any>`. Schema the initialization value of the field.
-
-For Formily Schema type support, please refer to [Customize input related type definition](/guides/topic-detail/generator/plugin/api/input/type).
-
-### getInputBySchemaFunc
-
-By schema to complete user interaction input, schema parameter value as function, the user handles globalization problems, and only supports Formily schema.
-
-Parameter:
-
-- schema: `config?: Record<string, any>) => FormilySchema`. Get the problem list function, the config parameter is the config configuration information in the current generator.
-- configValue: `Record<string, unknown> = {}`. Schema default value, the problem corresponding to the schema field passed in this value will no longer interact with the user.
-- validateMap?: `Record<string, (input: unknown, data?: Record<string, unknown>) => { success: boolean; error?: string }>`. Validation function for special fields in schema.
-- initValue?: `Record<string, any>`. Schema the initialization value of the field.
-
-For Formily Schema type support, please refer to [Customize input related type definition](/guides/topic-detail/generator/plugin/api/input/type).

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

@@ -1,56 +0,0 @@
----
-sidebar_position: 6
----
-
-# @modern-js/codesmith-api-ejs
-
-An API wrapper for file operations using [ejs] (https://ejs.co/) in microgenerators, providing a way to render individual template files and folders.
-
-## Use
-
-```ts
-import { EjsAPI } from '@modern-js/codesmith-api-ejs';
-
-export default async (context: GeneratorContext, generator: GeneratorCore) => {
-  const ejsAPI = new EjsAPI(generator);
-  await ejsAPI.renderTemplate(
-     material.get('templates/a.js'),
-     target: 'b.js',
-     { data: "data" }
-   );
-}
-```
-
-- Create EjsAPI 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
-
-### renderTemplate
-
-Render a single template file.
-
-Parameter:
-
-- templateResource: `FsResource`. Template file resource, used by `context.materials.get(<filename>)`.
-- target: `string`. Target file path name.
-- parameters?: `Record<string, string>`. Render parameter.
-
-### renderTemplateDir
-
-Render template folder.
-
-Parameter:
-
-- material: `FsMaterial`. The material context of the current microgenerator execution.
-- findGlob: `string`. Template file matches the regular.
-- target: `(globMatch: string) => string`. The target file path generation function, the parameter is `resourceKey.`
-- options?: `RenderTemplateDirOptions`. Glob Find the file configuration, the specific function viewable is here [glob] (https://www.npmjs.com/package/glob).
-
-```ts
-type RenderTemplateDirOptions = {
-  nodir?: boolean;
-  dot?: boolean;
-  ignore?: string | readonly string[];
-};
-```

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

@@ -1,54 +0,0 @@
----
-sidebar_position: 3
----
-
-# @modern-js/codesmith-api-fs
-
-API wrapper for file operations in microgenerators, providing methods to render individual template files and folders. FsAPI is usually used to handle binaries or template files that cannot be handled with handlebars, ejs.
-
-## Use
-
-```ts
-import { FsAPI } from '@modern-js/codesmith-api-fs';
-
-export default async (context: GeneratorContext, generator: GeneratorCore) => {
-  const fsApi = new FsAPI(generator);
-  await fsApi.renderFile(
-     material.get('templates/a.js'),
-     target: 'b.js'
-   );
-}
-```
-
-- Create FsAPI 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
-
-### renderFile
-
-Render a single template file.
-
-Parameter:
-
-- resource: `FsResource`. Template file resource, used by `context.materials.get(<filename>)`.
-- target: `string`. Target file path name.
-
-### renderDir
-
-Render template folder.
-
-Parameter:
-
-- material: `FsMaterial`. The material context of the current microgenerator execution.
-- findGlob: `string`. Template file matches the regular.
-- target: `(globMatch: string) => string`. The target file path generation function, the parameter is `resourceKey.`
-- options?: `RenderTemplateDirOptions`. Glob Find the file configuration, the specific function viewable is here [glob] (https://www.npmjs.com/package/glob).
-
-```ts
-type RenderTemplateDirOptions = {
-  nodir?: boolean;
-  dot?: boolean;
-  ignore?: string | readonly string[];
-};
-```

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

@@ -1,50 +0,0 @@
----
-sidebar_position: 4
----
-
-# @modern-js/codesmith-api-git
-
-The API encapsulation of git-related operations in the micro-generator provides methods for judging git repository, initialization and commit code.
-
-## Use
-
-```ts
-import { GitAPI } from '@modern-js/codesmith-api-git';
-
-export default async (context: GeneratorContext, generator: GeneratorCore) => {
-  const gitApi = new GitAPI(generatorCore, generatorContext);
-  await gitApi.initGitRepo();
-};
-```
-
-- Create GitAPI 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
-
-### isInGitRepo
-
-Whether the current directory is a git repository.
-
-Parameter:
-
-- cwd?: `string`. The execution directory of the git command, the default is microgenerator `outputPath`.
-
-### initGitRepo
-
-The initialization is the git repository. The default branch name for init can be configured via `defaultBranch` in the generator config.
-
-Parameter:
-
-- cwd?: `string`. The execution directory of the git command, the default is microgenerator `outputPath`.
-- force?: `boolean`. Use this parameter to force git init when the current directory is already a git repository.
-
-### addAndCommit
-
-Execute `git add .` and `git commit` commit the current changes.
-
-Parameter:
-
-- commitMessage: `string`. Commit information.
-- cwd?: `string`. The execution directory of the git command, the default is microgenerator `outputPath`.

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

@@ -1,57 +0,0 @@
----
-sidebar_position: 5
----
-
-# @modern-js/codesmith-api-handlebars
-
-An API wrapper for file operations using [handlebars] (https://handlebarsjs.com/) in the microgenerator, providing a way to render individual template files and folders.
-
-## Use
-
-```ts
-import { HandlebarsAPI } from '@modern-js/codesmith-api-handlebars';
-
-export default async (context: GeneratorContext, generator: GeneratorCore) => {
-  const handlebarApi = new HandlebarsAPI(generator);
-  await handlebarsAPI.renderTemplate(
-     material.get('templates/a.js'),
-     target: 'b.js',
-     { data: "data" }
-   );
-}
-```
-
-- Create HandlebarsAPI 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
-
-### renderTemplate
-
-Render a single template file.
-
-Parameter:
-
-- templateResource: `FsResource`. Template file resource, used by `context.materials.get(<filename>)`.
-- target: `string`. Target file path name.
-- parameters?: `Record<string, string>`. Render parameter.
-
-### renderTemplateDir
-
-Render template folder.
-
-Parameter:
-
-- material: `FsMaterial`. The material context of the current microgenerator execution.
-- findGlob: `string`. Template file matches the regular.
-- target: `(globMatch: string) => string`. The target file path generation function, the parameter is `resourceKey.`
-- options?: `RenderTemplateDirOptions`. Glob Find the file configuration, the specific function viewable is here [glob] (https://www.npmjs.com/package/glob).
-
-```ts
-type RenderTemplateDirOptions = {
-  nodir?: boolean;
-  dot?: boolean;
-  ignore?: string | readonly string[];
-};
-```

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

@@ -1,56 +0,0 @@
----
-sidebar_position: 2
----
-
-# @modern-js/codesmith-api-json
-
-The JSON API encapsulation in the microgenerator provides common JSON file operation methods.
-
-## Use
-
-```ts
-import { JsonAPI } from '@modern-js/codesmith-api-json';
-
-export default async (context: GeneratorContext, generator: GeneratorCore) => {
-  const jsonAPI = new JsonAPI(generator);
-  await jsonAPI.update(context.materials.default.get('package.json'), {
-    query: {},
-    update: {
-      $set: {
-        'dependencies.@modern-js/plugin-bff': `^2.0.0`,
-      },
-    },
-  });
-};
-```
-
-- Create JsonAPI 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
-
-### get
-
-Get the JSON file content.
-
-Parameter:
-
-- resource: `FsResource`. A file resource, get by `context.materials.default.get(<filename>)`.
-
-### extend
-
-Merge objects into a JSON file.
-
-Parameter:
-
-- resource: `FsResource`. A file resource, get by `context.materials.default.get(<filename>)`.
-- obj: `Record<string, any>`. Object to be merged.
-
-### update
-
-pdate object fields to JSON file.
-
-Parameter:
-
-- resource: `FsResource`. A file resource, get by `context.materials.default.get(<filename>)`.
-- operation: `{ query: Record<string, any>; update: Record<string, any> }`. Update operation, use gesture to view [declaration-update](https://www.npmjs.com/package/declaration-update) in detail.

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

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

@@ -1,53 +0,0 @@
----
-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@latest --generator <generatorName>` to run customized micro-generators.
-
-:::

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

@@ -1,47 +0,0 @@
----
-sidebar_position: 1
----
-
-# What is a microgenerator
-
-Modern.js provides the `@modern-js/create` tool and the `new` command for initialization to create projects and the ability to enable some plugin functions, respectively, these tools are based on microgenerators, also known as codesmith implementations.
-
-Codesmith is committed to providing a set of micro-generator operating mechanism, and maintain the context information in the execution process of the micro-generator, so as to implement various operations based on files, commands, etc., to complete sophisticated operations.
-
-Codesmith also encapsulates the commonly used methods, and can directly use the API functions it provides, which can more easily implement its own micro-generator.
-
-## Core concept
-
-### GeneratorCore
-
-GeneratorCore is the core of codesmith running generator, maintaining the context and running methods during the execution of the generator.
-
-```ts
-class GeneratorCore {
-  logger: ILogger;
-  materialsManager: MaterialsManager;
-  outputPath: string;
-  output:
-    fs: (file: string | number, data: any, options?: fs.WriteFileOptions | string) => Promise<void>;
-  };
-  _context: GeneratorContext;
-  addMaterial(key: string, material: FsMaterial): void;
-  runGenerator(generator: string, config?: Record<string, unknown>): Promise<void>;
-  runSubGenerator(subGenerator: string, relativePwdPath?: string, config?: Record<string, any>): Promise<void>;
-}
-```
-
-### Materials
-
-The micro-generator resource information currently only includes file resources (fsMaterials). Through this field, the template resources in the generator execution process can be obtained and operated through the API.
-
-```ts
-class MaterialsManager {
-  materialMap: {
-    // 资源映射关系
-    [materialUri: string]: FsMaterial;
-  };
-  loadLocalGenerator(generator: string): Promise<FsMaterial>;
-  loadRemoteGenerator(generator: string): Promise<FsMaterial>;
-}
-```

package/docs/en/guides/topic-detail/generator/codesmith/run-in-js.mdx

@@ -1,47 +0,0 @@
----
-sidebar_position: 4
----
-
-# Execute microgenerator with JS code
-
-In addition to using the cli method to execute the micro generator, we inevitably need to execute the micro generator in the code. The following describes how to execute the micro generator in the js code.
-
-## install codesmith dependency
-
-```bash
-pnpm add @modern-js/codesmith
-```
-
-## Create codesmith instance
-
-```ts
-import { CodeSmith, Logger } from '@modern-js/codesmith';
-
-const smith = new CodeSmith({
-  debug: false, //Whether to enable debug mode, if true, the debug information in the generator will be displayed
-});
-```
-
-## Call the forge method to execute the generator
-
-```ts
-type RunnerTask = Array<{
-  name: string;
-  config: Record<string, any>;
-}>;
-
-const task: RunnerTask = [
-  {
-    name: 'generator', // generator npm package name
-    config: {}, //The default configuration performed by the generator
-  },
-];
-
-await smith.forge({
-  tasks: task.map(runner => ({
-    generator: runner.name,
-    config: runner.config,
-  })),
-  pwd: '.', // generator implementation path
-});
-```