@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

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

@@ -0,0 +1,47 @@
+---
+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/en/guides/topic-detail/generator/codesmith/run-in-js.mdx

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

package/en/guides/topic-detail/generator/codesmith/structure.mdx

@@ -0,0 +1,89 @@
+---
+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:
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+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/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/abstract.mdx

@@ -0,0 +1,23 @@
+---
+sidebar_position: 1
+---
+
+# Why do you need a generator plugin
+
+Modern.js provides application, 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/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.

package/en/guides/topic-detail/generator/plugin/api/file/addManyFile.mdx

@@ -0,0 +1,58 @@
+---
+sidebar_position: 5
+---
+
+# addManyFile
+
+Import in batches file. Multiple files for adding the `templates` directory.
+
+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 AddManyFilesParams {
+  type: FileType;
+  destination: string;
+  templateFiles: string[] | (() => string[]);
+  templateBase?: string;
+  fileNameFunc?: (name: string) => string;
+  data?: Record<string, string>; // template data
+}
+export type ForgedAPI = {
+  addManyFiles: (params: AddManyFilesParams) => Promise<void>;
+  ...
+};
+```
+
+## type
+
+File type, specific viewable[File type](/guides/topic-detail/generator/plugin/api/file/introduce).
+
+## destination
+
+Create the target folder path. Since it is an import in batches file, fill in the folder path that needs to be written here.
+
+## templateFiles
+
+List of template files.
+
+This parameter supports the function parameter, as well as [globby](https://www.npmjs.com/package/globby).
+
+## templateBase
+
+Template base path.
+
+The template path is usually the template file in the same directory. If the render result needs to remove the template file prefix directory, this field can be used.
+
+Template render file content will be equal to `templateFiles - templateBase`
+
+## fileNameFunc
+
+Rename file function, where the file name of render is passed in once, and can be renamed in this function.
+
+## data
+
+Handlebars renders data.

package/en/guides/topic-detail/generator/plugin/api/file/introduce.mdx

@@ -0,0 +1,39 @@
+---
+sidebar_position: 1
+---
+
+# Introduction
+
+The file operation API can be used in the `onForged` time to live function, which can add, delete and change the current project file.
+
+File operation API related path to fill in the project relative path, generator plugin will automatically add the current project path prefix.
+
+## File type
+
+The generator plugin divides file types into the following categories:
+
+- Text files: plain text content files, files that can be templated using handlebars.
+
+- Binary files: pictures, audio, video and other files.
+
+:::warning
+The jsx or tsx file using the variable is a binary file, and its syntax conflicts with handlebars render, which will cause the template file failed to create.
+
+:::
+
+- JSON files: Files in JSON format, such as `package.json`, `tsconfig.json`.
+
+- Text List File: A file consisting of lines of text, such as `.gitignore`, `.editorconfig`, `.npmrc`.
+
+The file manipulation API for the generator plugin will operate on these four file types.
+
+Its type is defined as:
+
+```ts
+export enum FileType {
+  Text = 'text',
+  Binary = 'binary',
+  Json = 'json',
+  TextRaw = 'textRaw',
+}
+```

package/en/guides/topic-detail/generator/plugin/api/file/updateJSONFile.mdx

@@ -0,0 +1,54 @@
+---
+sidebar_position: 6
+---
+
+# updateJSONFile
+
+Update the JSON file fields.
+
+This method is suitable for JSON file types, and can batch update field values in JSON files.
+
+This method is available on the `onForged` time to live API parameter.
+
+Its type is defined as:
+
+```ts
+export type ForgedAPI = {
+  updateJSONFile: (
+    fileName: string,
+    updateInfo: Record<string, unknown>,
+  ) => Promise<void>;
+  ...
+};
+```
+
+## fileName
+
+The filename or file path of the JSON file.
+
+## updateInfo
+
+Field update information.
+
+This information is represented in Record form.
+
+For example, the name field needs to be updated:
+
+```ts
+api.updateJSONFile(file, {
+  name: 'new name',
+});
+```
+
+Nested fields need to be updated:
+
+```ts
+api.updateJSONFile(file, {
+  'dependencies.name': 'new name',
+});
+```
+
+:::warning
+Pay attention to the field name when updating the nested field. If it is not a total volume update, the nested key should also be written into the field name.
+
+:::