@modern-js/main-doc 2.1.0 → 2.2.0

package/en/guides/topic-detail/framework-plugin/relationship.mdx

@@ -0,0 +1,119 @@
+---
+title: 插件之间的关系
+sidebar_position: 4
+---
+# 插件之间的关系
+
+Modern.js 的插件配置对象提供了一系列的字段，用于控制插件顺序、互斥等能力，可用的字段如下：
+
+- `name`: `string`，设置当前插件的名称。
+- `pre`: `string[]`，这些插件最终会调整到当前插件前面。
+- `post`: `string[]`，这些插件最终会调整到当前插件后面。
+- `rivals`: `string[]`，互斥插件，遇到这些插件时会报错。
+- `required`: `string[]`，必需插件，插件列表中没有对应的插件时会报错。
+- `usePlugin`: `CliPlugin[]`，注册其他插件。
+
+通过以上参数可以实现插件的前置、后置、互斥、必需等逻辑。
+
+## 插件排序
+
+Modern.js 的插件通过 `pre`、`post` 参数来实现了插件排序的功能。
+
+### 前置插件
+
+默认情况下，插件会按照添加顺序依次执行，通过 `pre` 字段可以声明前置执行的插件。
+
+比如有下面两个插件：
+
+```ts title=foo.ts
+const foo = {
+  name: 'plugin-foo',
+};
+```
+
+```ts title=bar.ts
+const bar = {
+  name: 'plugin-bar',
+  pre: ['plugin-foo'],
+};
+```
+
+`bar` 插件在 `pre` 字段中配置了 `foo` 插件，因此 `foo` 插件一定会在 `bar` 插件之前执行。
+
+### 后置插件
+
+同样的，通过 `post` 字段可以声明后置执行的插件。
+
+```ts title=foo.ts
+const foo = {
+  name: 'plugin-foo',
+};
+```
+
+```ts title=bar.ts
+const bar = {
+  name: 'plugin-bar',
+  post: ['plugin-foo'],
+};
+```
+
+`bar` 插件在 `post` 字段中配置了 `foo` 插件，因此 `foo` 插件一定会在 `bar` 插件之后执行。
+
+## 互斥插件
+
+通过 `rivals` 字段可以声明插件间的互斥关系。
+
+有下面两个插件：
+
+```ts title=foo.ts
+const foo = {
+  name: 'plugin-foo',
+};
+```
+
+```ts title=bar.ts
+const bar = {
+  name: 'plugin-bar',
+  rivals: ['plugin-foo'],
+};
+```
+
+`bar` 插件在 `rivals` 字段中配置了 `foo` 插件，因此同时添加了 `foo` 插件和 `bar` 插件就会报错。
+
+## 必需插件
+
+通过 `required` 字段可以声明插件间的依赖关系。
+
+有下面两个插件：
+
+```ts title=foo.ts
+const foo = {
+  name: 'plugin-foo',
+};
+```
+
+```ts title=bar.ts
+const bar = {
+  name: 'plugin-bar',
+  required: ['plugin-foo'],
+};
+```
+
+`bar` 插件在 `required` 字段中配置了 `foo` 插件，因此使用 `bar` 插件时，如果未配置 `foo` 插件就会报错。
+
+## 注册插件
+
+当插件之间存在依赖关系时，我们也可以在一个插件中通过 `usePlugin` 主动注册另一个插件：
+
+```ts title=foo.ts
+const foo = () => ({
+  name: 'plugin-foo',
+});
+
+const bar = () => ({
+  name: 'plugin-bar',
+  usePlugin: [foo()],
+});
+```
+
+当使用者配置了 `bar` 插件时，`foo` 插件也会自动注册生效，使用者就不需要去额外注册 `foo` 插件了。

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

@@ -0,0 +1,152 @@
+---
+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/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 Management Tool 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/en/guides/topic-detail/generator/config/common.mdx

@@ -0,0 +1,100 @@
+---
+sidebar_position: 1
+---
+
+# Generator Configuration
+
+### solution
+
+Engineering solution type (solution), the options are as follows:
+
+- Application(mwa)
+
+- Module(module)
+
+- Monorepo
+
+:::info
+Solution configuration can only be used in the `--config` parameter of `@modern-js/create`, not by setting the default value in the generator plugin.
+
+:::
+
+### scenes
+
+Project scenarios (scenes), when using the generator plugin that creates the project scene type, this value is the key value of the corresponding generator plugin.
+
+:::info
+scenes configuration can only be used in the `--config` parameter of `@modern-js/create`, not by setting the default value in the generator plugin.
+
+:::
+
+### language
+
+Development language (language), the options are as follows:
+
+- TS(ts)
+
+- ES6+(js)
+
+### packageManager
+
+Package management tool (packageManager), the options are as follows:
+
+- pnpm(pnpm)
+
+- Yarn(yarn)
+
+:::info
+In the custom type of the generator plugin to create a project scenario, only the `packageManager` configuration is provided by default.
+
+:::
+
+## Other configurations
+
+### noNeedInstall
+
+- Type: `boolean`
+- Default: `false`
+
+Whether to skip the dependency installation.
+
+### noNeedGit
+
+- Type: `boolean`
+- Default: `false`
+
+Whether to skip git initialization and commit initial commit.
+
+### successInfo
+
+- Type: `string`
+- Default: Command operation prompts for different project schemes.
+
+Customize prompt information to create project success.
+
+### isMonorepoSubProject
+
+- Type: `boolean`
+- Default: `false`
+
+Whether it is a Monorepo subproject.
+
+### isTest
+
+- Type: `boolean`
+- Default: `false`
+
+Works on an Application project to identify whether it is a test project.
+
+- `true`: create project to `examples/`
+- `false`: create project to `apps/`
+
+### isPublic
+
+- Type: `boolean`
+- Default: `false`
+
+Used in the Module project to identify whether it needs to be published to npm.
+
+- `true`: create project to `packages/`
+- `false`: create project to `features/`

package/en/guides/topic-detail/generator/config/module.mdx

@@ -0,0 +1,42 @@
+---
+sidebar_position: 3
+---
+
+# Module
+
+## 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).
+
+### packageName
+
+Package name (packageName), character string type.
+
+## New Command
+
+The new command configuration in the module project can be used through the `--config` parameter configuration when executing the new command, or when enabling functions in the generator plugin.
+
+### actionType
+
+The action type (actionType) of the New command, he type supports one:
+
+- 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.
+
+:::
+
+### function
+
+Optional function name (function), supports the following options:
+
+- Tailwind CSS(tailwindcss)
+
+- Storybook(mwa_storybook)
+
+- Runtime API(runtimeApi)
+
+- Test(test)

package/en/guides/topic-detail/generator/config/monorepo.mdx

@@ -0,0 +1,28 @@
+---
+sidebar_position: 4
+---
+
+# Monorepo
+
+Monorepo projects only need [PackageManager](/guides/topic-detail/generator/config/common#packagemanager).
+
+## Create subproject
+
+The Monorepo project supports the creation of sub-projects by using the new command. The sub-project type supports application, test application, module, internal module. In addition to the respective configuration of the application and module, some general sub-project configuration is required here.
+
+### solution
+
+Subproject type(solution)，the different subproject type fields are:
+
+- Application (mwa)
+- Application (Test) (mwa_test)
+- Module
+- Modules (internal) (inner_module)
+
+### packageName
+
+Subproject name (packageName), character `string` type.
+
+### packagePath
+
+Subproject path (packagePath), character `string` type.

package/en/guides/topic-detail/generator/config/mwa.mdx

@@ -0,0 +1,82 @@
+---
+sidebar_position: 2
+---
+
+# MWA
+
+## 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/en/guides/topic-detail/generator/plugin/api/file/addFile.mdx

@@ -0,0 +1,52 @@
+---
+sidebar_position: 4
+---
+
+# addFile
+
+Add a single file. Use to add a single template file to the `templates` directory or add to a template file directly using templates.
+
+This method can be used with any file type, for file types other than binary, Handlebars render is performed when files are added.
+
+This method is available on the `onForged` time to live API parameter.
+
+Its type is defined as:
+
+```ts
+export interface AddFileParams {
+  type: FileType;
+  file: string;
+  template?: string;
+  templateFile?: string;
+  force?: boolean;
+  data?: Record<string, string>;
+}
+export type ForgedAPI = {
+  addFile: (params: AddFileParams) => Promise<void>;
+  ...
+};
+```
+
+## type
+
+File type, specific viewable[File type](/guides/topic-detail/generator/plugin/api/file/introduce).
+
+## file
+
+The path to the created target file.
+
+## template
+
+File template, configuration This field value can be used directly for template render files. The priority is lower than `templateFile`.
+
+## templateFile
+
+Template file, the template file path used for rendering, its value is the relative path of `templates`.
+
+## force
+
+Whether to force coverage, when the added file already exists, an error will be reported in conflict by default. When setting this value to true, coverage can be forced.
+
+## data
+
+Handlebars renders data.