@modern-js/main-doc 2.60.6 → 2.62.0

package/docs/en/guides/topic-detail/generator/create/option.md

@@ -1,146 +0,0 @@
----
-sidebar_position: 2
----
-
-# CLI Options
-
-`@modern-js/create` provides many configuration parameters to configure its behavior during execution, which can be viewed using the `--help` parameter:
-
-```bash
-npx @modern-js/create@latest --help
-
-Usage: npx @modern-js/create@latest [projectDir]
-
-create Modern.js solution project
-
-Options:
-  --version                show create tools version
-  --lang <lang>            set create tools language(en or zh)
-  -c, --config <config>    set default project config(json string) (default: "{}")
-  -d,--debug               using debug mode to log something (default: false)
-  --mwa                    create mwa application using default config (default: false)
-  --module                 create module application using default config (default: false)
-  --generator <generator>  run custom generator
-  -p, --plugin <plugin>    use generator plugin to create new solution or customize Modern.js solution (default: [])
-  --dist-tag <distTag>     use specified tag version for it\'s generator (default: "")
-  --packages <packages>    set project specific dependency version information (default: "{}")
-  --registry <registry>    set npm registry url to run npm command (default: "")
-  --no-need-install        not run install command
-  -h, --help               display help for command
-
-Commands:
-  clean-cache              clean locale generator cache
-```
-
-The following will provide a detailed introduction to these parameters:
-
-## [projectDir]
-
-The project directory name.
-
-When executing `@modern-js/create`, a `projectDir` folder will be created in the current directory by default, and the project will be initialized in this folder. If this parameter is empty, the initialization project will be directly generated in the current directory.
-
-:::info
-If the contents of the directory where `projectDir` is located are not empty, a prompt will be given whether to continue creating. It is recommended to perform project initialization operations in an empty directory.
-:::
-
-## --version
-
-Get the version of the `@modern-js/create` tool.
-
-```bash
-npx @modern-js/create@latest --version
-
-[INFO] @modern-js/create v2.21.1
-```
-
-## --lang \<lang>
-
-The execution language, supports `zh` and `en`.
-
-By default, `@modern-js/create` will automatically identify the user's system language and choose to use Chinese or English. If the identification fails or does not meet usage habits, you can manually specify it using this parameter.
-
-## -c, --config \<config>
-
-Specify the default project configuration.
-
-By default, `@modern-js/create` will prompt for interactive questions such as language selection and package managers during the execution process. When it is necessary to specify these configuration contents in advance, they can be passed in through this field.
-
-This field is a JSON string. For example, when specifying a package manager:
-
-```bash
-npx @modern-js/create@latest --config '{"packageManager": "pnpm"}'
-```
-
-Supported parameters for `config` can be found at [Configuration Parameters](/guides/topic-detail/generator/create/config.html)。
-
-## -d,--debug
-
-Display debug logs.
-
-When encountering problems during use, you can use this parameter to display debug logs, which is convenient for quickly locating the problem position and troubleshooting.
-
-## --mwa
-
-Quickly create a Web App project.
-
-## --module
-
-Quickly create a Npm Module project.
-
-## -p, --plugin \<plugin>
-
-Specify a generator plugin.
-
-`@modern-js/create` supports customizing the default project solution type of Modern.js or adding project solution type scenarios using generator plugin. For details, please refer to [Developing Generator Plugin](/guides/topic-detail/generator/plugin/structure.html).
-
-## --generator \<generator>
-
-Specify a micro-generator.
-
-<!-- TODO 详情可查看[开发微生成器]-->
-`@modern-js/create` supports completely customizing the project generation process using micro-generator.
-
-## --dist-tag \<distTag>
-
-Specify the version of the generator and Modern.js-related dependencies.
-
-During the execution of `@modern-js/create`, a smaller micro-generator will be executed by default, and the `latest` version of the micro-generator will be used by default. This parameter can be used to specify the version number of the micro-generator to be executed and the version of the installed Modern.js-related dependencies.
-
-For example, use the `next` version:
-
-```bash
-npx @modern-js/create@next --dist-tag next
-```
-
-## --packages \<packages>
-
-Specify specific package version dependencies when creating a project.
-
-If you need to specify a specific package version when creating a project, you can use this parameter. This parameter will configure `pnpm.overrides` (if the package manager is pnpm) or `resolutions` to lock the package version number in the `package.json` file in the project root directory.
-
-The parameter value is a JSON string.
-
-For example, specify the react version:
-
-```bash
-npx @modern-js/create@latest --packages '{"react":"^17"}'
-```
-
-## --registry \<registry>
-
-Specify the sub-generator to execute and the npm registry to fetch project dependencies version.
-
-## --no-need-install
-
-Ignore automatic installation of dependencies.
-
-By default, `@modern-js/create` will automatically install dependencies after creating a project. Using this parameter can ignore the installation of dependencies.
-
-## clean-cache
-
-The `@modern-js/create` command generates sub-generators cache in the tmp directory of the execution machine by default to speed up the generator execution. This command can be used to delete the cache when it needs to be refreshed or when there are problems with the cache.
-
-```bash
-npx @modern-js/create@latest clean-cache
-```

package/docs/en/guides/topic-detail/generator/create/use.mdx

@@ -1,48 +0,0 @@
----
-sidebar_position: 1
----
-
-# Usage
-
-Modern.js provides `@modern-js/create` tool for creating project templates provided by Modern.js, including [Web App](https://modernjs.dev/), [Npm Module](https://modernjs.dev/module-tools).
-
-The following will introduce how to use `@modern-js/create`.
-
-## Environment Preparation
-
-import Prerequisites from "@site-docs-en/components/prerequisites"
-
-<Prerequisites />
-
-## Create a Project with `@modern-js/create`
-
-You do not need to install `@modern-js/create` globally, just use npx to run it:
-
-```bash
-npx @modern-js/create@latest [projectDir]
-```
-
-:::info
-`[projectDir]` is the project directory name. If it is not filled in, the project will be created in the current directory.
-:::
-
-During the execution, complete the interaction according to the prompt to create a project that meets your requirements.
-
-### Create an Web APP Project
-
-```bash
-npx @modern-js/create@latest web-app
-? Please select the type of project you want to create: Web App
-? Please select the programming language: TS
-? Please select the package manager: pnpm
-```
-
-### Create an Npm Module Project
-
-```bash
-npx @modern-js/create@latest npm-module
-? Please select the type of project you want to create: Npm Module
-? Please fill in the project name: npm-module
-? Please select the programming language: TS
-? Please select the package manager: pnpm
-```

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

@@ -1 +0,0 @@
-["use", "option", "config"]

package/docs/en/guides/topic-detail/generator/new/config.md

@@ -1,115 +0,0 @@
----
-sidebar_position: 3
----
-
-# Configuration Parameters
-
-The `new` command provides the [--config](/guides/topic-detail/generator/new/option.html#-c,---config-<config>) parameter, which is used to specify the answers to interactive questions in advance during the execution process.
-
-Here, we will introduce the fields and field values that can be configured in the `config` under different scenario.
-
-## General Configuration
-
-### actionType
-
-Question: Please select the operation you wants.
-
-Options:
-
-- Create project element -- element
-
-- Enable features -- function
-
-- Automatic refactors -- refactor
-
-## Web App
-
-### element
-
-Question: Please select the type of element to create.
-
-Options:
-
-- New "entry" -- entry
-
-- New "Custom Web Server" source code directory -- server
-
-### name
-
-Question: Please fill in the entry name.
-
-:::info
-This configuration is required when creating a new application entry, and the configuration value is a string.
-:::
-
-### function
-
-Question: Please select the feature name.
-
-Options:
-
-- Enable Rspack Build -- rspack
-
-- Enable Tailwind CSS -- tailwindcss
-
-- Enable BFF -- bff
-
-- Enable SSG -- ssg
-
-- Enable SWC Compile -- swc
-
-- Enable Micro Frontend -- micro_frontend
-
-- Enable UA-based Polyfill Feature -- polyfill
-
-- Enable Global Proxy -- proxy
-
-### bffType
-
-Question: Please select the BFF type
-
-Options:
-
-- Function -- func
-
-- Framework -- framework
-
-:::info
-This configuration is required when enabling the BFF function.
-:::
-
-### framework
-
-Question: Please select the framework.
-
-Options:
-
-- Express -- express
-
-- Koa -- koa
-
-:::info
-This configuration is required when enabling the BFF function.
-:::
-
-### refactor
-
-Question: Please select the type of refactoring.
-
-Options:
-
-- Use React Router v5 -- react_router_5
-
-## Npm Module
-
-### function
-
-Question: Please select the feature name.
-
-Options:
-
-- Enable Tailwind CSS -- tailwindcss
-
-- Enable Storybook -- storybook
-
-- Enable Runtime API -- runtime_api

package/docs/en/guides/topic-detail/generator/new/option.md

@@ -1,67 +0,0 @@
----
-sidebar_position: 2
----
-
-# CLI Parameters
-
-The `new` command provides many configuration parameters to configure its behavior during execution, which can be viewed using the `--help` parameter:
-
-```bash
-npm run new --help
-
-Usage: modern new [options]
-
-enable optional features or add a new entry
-
-Options:
-  --lang <lang>          set new command language(en or zh)
-  -c, --config <config>  set default generator config(json string)
-  -d, --debug            using debug mode to log something (default: false)
-  --dist-tag <tag>       use specified tag version for it's generator
-  --registry <registry>  set npm registry url to run npm command
-  -h, --help             display help for command
-```
-
-The following will provide a detailed introduction to these parameters:
-
-## --lang \<lang>
-
-The language used for execution, supports `zh` and `en`.
-
-By default, the `new` command will automatically recognize the user's system language and choose to use Chinese or English. If recognition fails or does not meet usage habits, this parameter can be used to manually specify it.
-
-## -c, --config \<config>
-
-Specify the default configuration for the project.
-
-By default, the `new` command will prompt interactive questions during the execution process for selecting operation types, enabling features, etc. When it is necessary to specify these configuration contents in advance, they can be passed in through this field.
-
-This field is a JSON string. For example, to specify the BFF framework:
-
-```bash
-npm run new --config '{"framework": "express"}'
-```
-
-The parameters supported by `config` can be viewed in [Configuration Parameters](/guides/topic-detail/generator/new/config.html)。
-
-## -d,--debug
-
-Displays debug logs.
-
-When encountering problems during use, this parameter can be used to display debug logs, which is convenient for quickly locating the problem location and troubleshooting the problem.
-
-## --registry \<registry>
-
-Specify the sub-generator to execute and the npm registry to fetch project dependencies version.
-
-## --dist-tag \<distTag>
-
-Specify the generator version.
-
-During the execution process of the `new` command, smaller micro-generator will be executed by default, and the latest micro-generator version will be used by default. This parameter can be used to specify the version number of the micro-generator to be executed.
-
-For example, using the `next` version:
-
-```bash
-npm run new --dist-tag next
-```

package/docs/en/guides/topic-detail/generator/new/use.md

@@ -1,75 +0,0 @@
----
-sidebar_position: 1
----
-
-# Usage
-
-In Web App, Npm Module projects, we provide the `new` command to create project elements, enable features and create sub-project.
-
-## Web App
-
-Web App projects use the `new` command provided by `@modern-js/app-tools`.
-
-
-The `new` command provides three types of operations:
-
-- Create project elements
-
-- Enable optional features
-
-- Automatic refactoring
-
-Each type of operation provides a corresponding list of supported options, which can be selected based on the project situation.
-
-For example:
-
-Create a new application entry:
-
-```bash
-npm run new
-? Please select the operation you want: Create Element
-? Please select the type of element to create: New "entry"
-? Please fill in the entry name: entry
-```
-
-After running, a new folder with the corresponding name of the entry will be created in the `src` directory of the project, along with the default entry file. The previous entry files under the `src` directory will be sorted into the folder corresponding to the `name` field in `package.json`.
-
-Enable BFF function:
-
-```bash
-npm run new
-? Please select the operation you want: Enable Features
-? Please select the feature name: Enable BFF
-? Please select the BFF type: Function
-? Please select the framework: Express
-```
-
-After running, BFF-related dependencies will be installed in the project, and an `api` directory will be created for BFF module development, along with prompt information for registering BFF plugins.
-
-:::info
-We did not automatically register the plugin for the user here because the `modern.config.[tj]s` may change during the project lifecycle, and there may be problems with mutual references between modules, so allowing the user to manually register can ensure the correctness of modifying the configuration.
-
-In subsequent customized development, if there are similar needs, you can also provide users with operational guidance through prompts, allowing users to manually operate on files.
-:::
-
-:::warning
-When running the `new` command, it may be necessary to enable a feature that is not in the list. Check whether the corresponding plugin for the feature has been installed in the `package.json` file of the project. If you still need to use the `new` command to enable it, you need to manually remove the plugin dependency first.
-:::
-
-## Npm Module
-
-Npm Module projects use the `new` command provided by `@modern-js/module-tools`.
-
-The `new` command provides the ability to enable optional features.
-
-For example:
-
-Enable Storybook capability:
-
-```bash
-npm run new
-? Please select the operation you want: Enable Features
-? Please select the feature name: Enable Storybook
-```
-
-After running, Storybook plugin dependencies will be installed in the project, and the `storybook` command will be added. A `stories` directory will be created for Storybook module development, along with prompt information for registering Storybook plugins.

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