@modern-js/main-doc 2.0.0-beta.1 → 2.0.0-beta.2

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/codesmith/api/json.md

@@ -0,0 +1,59 @@
+---
+sidebar_position: 2
+---
+
+# @modern-js/codesmith-api-json
+
+The JSON API encapsulation in the microgenerator provides common JSON file operation methods.
+
+## Use
+
+```typescript
+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/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/codesmith/api/npm.md

@@ -0,0 +1,49 @@
+---
+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 management tools.
+
+## Use
+
+```typescript
+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/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/codesmith/develop.md

@@ -0,0 +1,52 @@
+---
+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/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/codesmith/introduce.md

@@ -0,0 +1,46 @@
+---
+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.
+
+```typescript
+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.
+
+```typescript
+class MaterialsManager {
+  materialMap: { // 资源映射关系
+    [materialUri: string]: FsMaterial;
+  };
+  loadLocalGenerator(generator: string): Promise<FsMaterial>;
+  loadRemoteGenerator(generator: string): Promise<FsMaterial>;
+}
+```

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/codesmith/run-in-js.md

@@ -0,0 +1,48 @@
+---
+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
+
+```typescript
+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
+
+```typescript
+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
+});
+```

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/codesmith/structure.md

@@ -0,0 +1,87 @@
+---
+sidebar_position: 2
+---
+
+# The composition of the microgenerator
+
+A microgenerator project is a module project or an Npm package that contains several basic parts:
+
+## package.json
+
+NPM package description information, including name, version, main and other fields.
+
+## Entry file
+
+The js file corresponding to the above main field. The file exports a generator function by default, and the function format is as follows:
+
+```typescript
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+
+};
+```
+
+The function parameters are context and generator:
+
+### context
+
+Context provides context information maintained by the codesmith runtime. Its type is defined as:
+
+```typescript
+interface GeneratorContext {
+  materials: Record<string, FsMaterial>;
+  config: Record<string, any>;
+  data?: Record<string, any>;
+  current: { material: FsMaterial; } | null;
+  [key: string]: any;
+}
+```
+
+Materials is an abstract file system for codesmith that maintains the mapping between generator names and actionable files.
+
+Materials also maintains this default mapping relationship, which is used to maintain the resource information of the current generator execution directory, and can operate on the target project resources through this field.
+
+For example, when you need to modify a field in the `package.json` of the current project:
+
+```typescript
+const resource = context.materials.default.get(path.join(appDir, 'package.json'))
+```
+
+Pass the acquired resources to the JSON API provided by codesmith to implement json operations.
+
+The currently running generator file resource is maintained on the current field of `GeneratorContext`, and the current `FsMaterial` can be obtained through `current.material`.
+
+The get method is provided in `FsMaterial` to get the resource file and pass the resource file to the API supported by the generator to process the template file.
+
+For example:
+
+```typescript
+const resourceMap = await material.find('templates/**/*');
+```
+
+All template files in the generator that match to the `templates /**/*` rules can be obtained in the above way, and the resource files can be operated by traversing the object.
+
+### generator
+
+Generator provides the function method of the codesmith runtime. Its type is defined as:
+
+```typescript
+interface GeneratorCore {
+    logger: Logger;
+    outputPath: string;
+    output: {
+        fs: (file: string | number, data: any, options?: string | fs.WriteFileOptions | undefined) => Promise<void>
+    };
+    runSubGenerator: (subGenerator: string, relativePwdPath?: string | undefined, config?: Record<string, any> | undefined): Promise<void>
+}
+```
+
+The outputPath and the `materials.default` in the context point to the same directory, the outputPath is used to directly calculate the target path and operate, and the `materials.default` is used to obtain resource files.
+
+
+`runSubGenerator` provides a way to run other microgenerators in one microgenerator, which will automatically update and maintain new context information.
+
+## Template File
+
+Generator template file.
+
+It is recommended to create a templates directory in the project root directory to maintain the template file of the microgenerator. During the execution of the microgenerator, you can only use your own template file. For template files that need to be shared, it is recommended to use a shared sub-generator implementation.

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/config/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Engineering configuration",
+  "position": 3
+}

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/config/common.md

@@ -0,0 +1,106 @@
+---
+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.
+:::
+
+## 其他配置
+
+### 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
+
+   - true: create project to `examples/`
+
+   - false: create project to `apps/`
+
+* Default: false
+
+Works on an Application (MWA) project to identify whether it is a test project.
+
+### isPublic
+
+* Type: Boolean
+
+   - true: create project to `packages/`
+
+   - false: create project to `features/`
+
+* Default: false
+
+Used in the Module project to identify whether it needs to be published to npm.

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/config/module.md

@@ -0,0 +1,39 @@
+---
+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](/docs/guides/topic-detail/generator/config/common).
+
+### packageName
+
+Package name (packageName), character string type.
+
+## New 命令
+
+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)

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/config/monorepo.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 4
+---
+
+# Monorepo
+
+Monorepo projects only need [PackageManager](/docs/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/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/config/mwa.md

@@ -0,0 +1,89 @@
+---
+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](/docs/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)
+
+These two options also need to be used in conjunction with the specific configuration, which is described as follows:
+
+#### name
+
+Entry name (name), character `string` type.
+
+#### framework
+
+Customized server runtime framework(framework)，supports two options:：
+
+- Express(express)
+
+- Koa(koa)
+
+### 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/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/plugin/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Development Generator Plugin",
+  "position": 4
+}

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/plugin/abstract.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 1
+---
+
+# Why do you need a generator plugin
+
+Modern.js provides application (MWA), modules and Monorepo three engineering solutions, and by using the `@modern-js/create` tool can create the initial project template of the three engineering solutions, the initial project template will provide basic code development environment, simple sample code and configuration, etc.
+
+Modern.js provides an initialization template that is versatile and can meet some general project development needs.
+
+When you use Modern.js in depth, you will inevitably find that every time you create a project, you will make some similar changes specific to your own project, such as modifying the sample code, adding some configuration, enabling some functions, etc.
+
+
+The generator plugin can help you precipitate these individual or team-specific changes. Simply bring the `--plugin` parameter when executing `npx @modern-js/create` to avoid the need to repeatedly modify the project every time the project is created..
+
+The generator plugin is based on the initialization template project provided by the Modern.js, providing methods to add, delete and modify templates, and modifying `package.json`, `modernConfig` configuration and opening functions in a fast way.
+
+The generator plugin provides two ways of customization:
+
+1. Extended engineering: directly customize the three major engineering provided by default.
+
+
+2. Create engineering scenes: Create corresponding engineering scenes based on the default three major engineering.
+
+
+The next step will introduce how to use and develop the generator plugin step by step.

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/plugin/api/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "API",
+  "position": 4
+}

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/plugin/api/file/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "File API",
+  "position": 6
+}