@modern-js/main-doc 0.0.0-nightly-20241104170657 → 0.0.0-nightly-20241106064312

package/docs/en/guides/topic-detail/generator/plugin/category.md

@@ -1,88 +0,0 @@
----
-sidebar_position: 2
----
-
-# Introduction
-
-There are two types of generator plugin:
-
-- Extension: Web App(Npm Module) = Web App(Npm Module) + Generator Plugin
-
-- Custom: New Application(Npm Module) = Web App(Npm Module) + Generator Plugin
-
-
-In simpler terms, extension means using the original project name of Modern.js, while custom means creating a new name.
-
-## Identifier
-
-The type of generator plugin is provided through the `meta` field in `package.json`:
-
-### Extension
-
-```json title="package.json"
-{
- "meta": {
-    "extend": "mwa" // module
- }
-}
-```
-
-### Custom
-
-```json title="package.json"
-{
- "meta": {
-    "key": "new_app",
-    "name": "new App",
-    "type": "mwa" // module and custom
- }
-}
-```
-
-:::info
-For custom type, the `type` field supports the `custom` value, which utilizes some best practice templates for project development provided by Modern.js, such as `.gitignore`, `.editorConfig`, etc. Other business-related code templates need to be manually provided through generator plugin.
-:::
-
-# Creating Initial Project
-
-### Extension
-
-```bash
-npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
-? Please select the type of project you want to create: Npm Module
-? Please select the project scenario: Generator Plugin
-? Please fill in the package name of the generator plugin: plugin
-? Please select the programming language: TS
-? Please select the package manager: pnpm
-? Please select the type of plugin: extend
-? Please select the base type of the plugin: Web App
-```
-
-### Custom
-
-```bash
-npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
-? Please select the type of project you want to create: Npm Module
-? Please select the project scenario: Generator Plugin
-? Please fill in the package name of the generator plugin: plugin
-? Please select the programming language: TS
-? Please select the package manager: pnpm
-? Please select the type of plugin: custom
-? Please fill in the plugin keyword: new_app
-? Please fill in the display name of the plugin: new App
-? Please select the base type of the plugin: Web App
-```
-
-## Execution Order
-
-Generator plugins support using multiple plugins at the same time, which means that multiple `--plugin` parameters are supported when executing `@modern-js/create`.
-
-### Extension
-
-For extension generator plugins, when executing with the declared generator plugin parameters, the corresponding lifecycle functions of the project scheme that is extended will be executed in order.
-
-For example, if there are two generator plugins A and B, both of which extend the Modern.js application scheme. A plugin declares to add the `a.ts` file, and B plugin declares to add the `b.ts` file. When executing `npx @modern-js/create@latest --plugin A --plugin B`, and selecting the Web APP scheme, the default project files of the Web APP will be generated first. Then, the A plugin will create the `a.ts` file, and then the B plugin will generate the `b.ts` file.
-
-### Custom
-
-For custom generator plugins, only one plugin can be executed at a time. When declaring the `--plugin` parameter for `@modern-js/create`, a selection option for the scenario of choosing the project scheme will be added after selecting the project scheme, which is the new name defined in the `package.json`. Choosing the corresponding generator plugin for the name will execute the corresponding generator plugin logic after the default project scheme is completed. When declaring the `--plugin` parameter, the corresponding generator plugin names will be listed one by one for selection in the project scheme scenario.

package/docs/en/guides/topic-detail/generator/plugin/context.md

@@ -1,104 +0,0 @@
----
-sidebar_position: 4
----
-
-# Context
-
-By default, generator plugins will export a function that takes `context` as a parameter. During execution, `context` will be automatically injected into the generator plugin.
-
-```ts title="src/index.ts"
-import { IPluginContext, ForgedAPI } from '@modern-js/generator-plugin';
-
-export default function (context: IPluginContext) {
-  context.onForged(async (_api: ForgedAPI, _input: Record<string, unknown>) => {
-    /**
-     * Todo
-     */
-  });
-}
-```
-`context` provides two types of APIs, which are used to customize input and define generator plugin lifecycle logic.
-
-:::info
-Only some APIs are briefly explained below. For the complete API, please refer to [Generator Plugin API](/guides/topic-detail/generator/plugin/api/context.html).
-:::
-
-## Customize Input
-
-Both Modern.js Framework and Modern.js Module have default input interactions. These APIs can be used to add, modify, hide, and provide default values for these inputs.
-
-For example:
-
-- Add question
-
-```ts
-context.addInputBefore('packageManager', {
-  type: 'object',
-  properties: {
-    'username': {
-      type: 'string',
-      title: 'Username',
-    },
-  },
-});
-```
-
-- Hide question by setting `config`
-
-```ts
-context.setDefaultConfig({ langauge: 'ts' });
-```
-
-## Lifecycle
-
-Generator plugin provide two lifecycle hooks to define generator plugin behavior:
-
-- `onForged`: Lifecycle after file operations are completed.
-
-- `afterForged`: Lifecycle after the `onForged` hook function is executed.
-
-## `onForged`
-
-Hook function after the Modern.js project scheme generator has completed file operations. It is used to complete file operations in the generator plugin, such as adding template files, overwriting existing files, deleting existing files, etc.
-
-When multiple generator plugins are executed simultaneously for extension type, the `onForged` operations of the corresponding generator plugins will be executed in order according to the declared order.
-
-The `onForged` function takes a callback function as a parameter, with `api` and `input` as arguments.
-
-```ts
-context.onForged(async (api: ForgedAPI, input: Record<string, unknown>) => {
-  const { language } = input;
-  api.addFile({
-      type: FileType.Text,
-      file: `src/index.${language as string}`,
-      templateFile: `index.${language as string}.handlebars`,
-      force: true,
-  });
-})
-```
-
-The `api` object provides file operation-related methods supported by generator plugin.
-
-`input` is the current user input, which includes the `--config` parameter definition, the default scheme interaction, and the user input defined by the generator plugin.
-
-When adding a new file template, define the template file in the `templates` directory, and then operate on it through the `api` method above. The generator plugin defaults to operating on files in the `templates` directory, so there is no need to declare the `templates` path.
-
-## `afterForged`
-
-Executed after the `onForged` hook function is completed. It is mainly used to install dependencies, perform git operations, etc.
-
-By default, Modern.js project scheme will install dependencies and initialize Git after completing file operations, and perform git initial submissions, etc. This hook function can be omitted.
-
-For custom generator plugins that also support the `custom` type, which only provides a small number of best practice project configurations, installation of dependencies and Git initialization operations need to be completed in this hook function.
-
-The `afterForged` function also takes a callback function as a parameter, with `api` and `input` as arguments.
-
-```ts
-  context.afterForged(
-    async (api: AfterForgedAPI, input: Record<string, unknown>) => {
-      const { packageManager } = input;
-      console.info('packageManager:', packageManager);
-      await api.install();
-    },
-  );
-```

package/docs/en/guides/topic-detail/generator/plugin/structure.md

@@ -1,106 +0,0 @@
----
-sidebar_position: 1
----
-
-# Introduction and Project Creation
-
-## Introduction
-
-Modern.js provides engineering solutions such as Web App and Npm Module. By using the `@modern-js/create` tool, you can create initial project templates for engineering solutions. The initial project template provides a basic code development environment, simple example code, and configuration, etc.
-
-The initial templates provided by Modern.js are generic and can meet some common project development needs.
-
-When you use Modern.js deeply, you will inevitably find that each created project will make some specific similar changes for its own project, such as modifying example code, adding some configurations, enabling certain features, etc.
-
-Generator plugin can help you to deposit these specific changes for individuals or teams. When running `npx @modern-js/create@latest`, you only need to simply add the `--plugin` parameter to avoid repetitive modification of the project after each project creation.
-
-Generator plugin is based on the initial template projects provided by Modern.js, providing methods to add, delete, and modify templates, and modifying `package.json`, `modernConfig` configurations, and enabling features through a convenient way.
-
-## Create Project
-
-Use `@modern-js/create` to create a generator plugin project directly:
-
-```bash
-npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
-? Please select the type of project you want to create: Npm Module
-? Please select the project scenario: Generator Plugin
-? Please fill in the package name of the generator plugin: plugin
-? Please select the programming language: TS
-? Please select the package manager: pnpm
-? Please select the type of plugin: extend
-? Please select the base type of the plugin: Web App
-```
-
-After creating, we can take a look at the directory structure of this project:
-
-```bash
-.
-├── .changeset
-│   └── config.json
-├── .eslintrc.js
-├── .gitignore
-├── .npmrc
-├── .nvmrc
-├── .prettierrc
-├── README.md
-├── modern.config.ts
-├── package.json
-├── src
-│   ├── modern-app-env.d.ts
-│   └── index.ts
-├── templates
-│   └── .gitkeep
-└── tsconfig.json
-```
-
-The project is based on the Npm module project, and the core files are as follows:
-
-```bash
-*
-├── package.json
-├── src
-│   └── index.ts
-├── templates
-│   └── .gitkeep
-```
-
-## package.json
-
-In addition to the normal fields of a module project, `package.json` provides a `meta` field to describe information about the generator plugin.
-
-Generator plugin is divided into two categories: extension and custom. For specific classification definitions, please refer to [Type](/guides/topic-detail/generator/plugin/category).
-
-```json title="package.json"
-{
-  ...,
-  "meta": {
-    "extend": "mwa"
-  }
-}
-```
-
-## src/index.ts
-
-This file is used to complete the content development of the generator plugin.
-
-```js
-import { IPluginContext, ForgedAPI } from '@modern-js/generator-plugin';
-
-export default function (context: IPluginContext) {
-  context.onForged(async (_api: ForgedAPI, _input: Record<string, unknown>) => {
-    /**
-     * todo
-     */
-  });
-}
-```
-
-This file exports a function by default, and the function takes `context` as a parameter. The `context` object provides API methods supported by the generator plugin, which can be used to implement the logic of the generator plugin. The capabilities provided by `context` can be found in [context](/guides/topic-detail/generator/plugin/context).
-
-## templates
-
-The `templates` directory contains template files for the current customization method, supporting [Handlebars](https://handlebarsjs.com/) and [EJS](https://ejs.co/) formats. Different rendering engines will be used for rendering according to the template file suffix. If there is no suffix, the template file will be copied directly to the target directory.
-
-If the template file is a `js`, `ts`, or `json` file, it is recommended to use the `.handlebars` or `.ejs` suffix directly to avoid project eslint errors and recognition issues in Monorepo projects.
-
-The `.gitignore` and `.npmrc` files in the template will be automatically deleted when publishing the npm package, so it is necessary to use the `.handlebars` or `.ejs` suffix to keep them.

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

@@ -1,33 +0,0 @@
----
-sidebar_position: 3
----
-
-# Usage
-
-`@modern-js/create` provides the `--plugin` parameter to run the generator plugin project.
-
-`--plugin` supports three formats:
-
-## Absolute path
-
-Suitable for local development and debugging. After development is completed, build the project by running `npm run build` in the generator plugin project, and then use the following command for testing:
-
-```bash
-npx @modern-js/create@latest --plugin <pluginPath>
-```
-
-## Relative path
-
-Suitable for local development and debugging or when the generator plugin project and the target project to be created are in the same Monorepo and there is no need to publish an NPM package. After building the generator plugin project, use the following command:
-
-```bash
-npx @modern-js/create@latest --plugin file:../<pluginPath>
-```
-
-## NPM package
-
-Suitable for scenarios where the generator project is published on npm for sharing.
-
-```bash
-npx @modern-js/create@latest --plugin <pluginPackage>
-```

package/docs/zh/guides/topic-detail/generator/_meta.json

@@ -1,17 +0,0 @@
-[
-  {
-    "type": "dir",
-    "name": "create",
-    "label": "@modern-js/create"
-  },
-  {
-    "type": "dir",
-    "name": "new",
-    "label": "new-command"
-  },
-  {
-    "type": "dir",
-    "name": "plugin",
-    "label": "generator-plugin"
-  }
-]

package/docs/zh/guides/topic-detail/generator/create/_meta.json

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

package/docs/zh/guides/topic-detail/generator/create/config.mdx

@@ -1,60 +0,0 @@
----
-sidebar_position: 3
----
-
-# 配置参数
-
-`@modern-js/create` 提供了 [--config](/guides/topic-detail/generator/create/option.html#-c,---config-<config>) 参数，用于提前指定执行过程中交互问题的答案。
-
-这里将介绍不同情况下，可以在 `config` 中配置的字段及字段值。
-
-
-## 通用配置
-
-### solution
-
-问题：请选择你想创建的工程类型
-
-选项：
-
-- Web 应用 -- mwa
-
-- Npm 模块 -- module
-
-- 文档站 -- doc
-
-### scenes
-
-问题：请选择项目场景
-
-选项：
-
-使用自定义生成器插件时的插件关键字列表。
-
-## Web 应用
-
-import LanguageConfig from '@site-docs/components/language-config';
-
-<LanguageConfig />
-
-import PackageManager from '@site-docs/components/package-manager';
-
-<PackageManager />
-
-## Npm 模块
-
-### packageName
-
-问题：请填写项目名称
-
-:::info
-Npm 模块的 `package.json` 的 name 字段值，该配置值为字符串类型。
-:::
-
-<LanguageConfig />
-
-<PackageManager />
-
-## 文档站
-
-<PackageManager />

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

@@ -1,146 +0,0 @@
----
-sidebar_position: 2
----
-
-# CLI 参数
-
-`@modern-js/create` 提供了很多配置参数用于配置其执行过程中的行为，可以通过 `--help` 参数进行查看：
-
-```bash
-npx @modern-js/create@latest --help
-
-Usage: npx @modern-js/create@latest [projectDir]
-
-创建 Modern.js 工程方案
-
-Options:
-  --version                当前 create 工具版本号
-  --lang <lang>            设置 create 工具语言(zh 或者 en)
-  -c, --config <config>    创建项目默认配置(JSON 字符串) (default: "{}")
-  -d,--debug               开启 Debug 模式，打印调试日志信息 (default: false)
-  --mwa                    一键创建 Web 应用(使用默认配置) (default: false)
-  --module                 一键创建 Module 应用(使用默认配置) (default: false)
-  --generator <generator>  使用自定义生成器
-  -p, --plugin <plugin>    使用生成器插件创建新的工程方案类型或定制化 Modern.js 工程方案 (default: [])
-  --dist-tag <distTag>     生成项目时生成器使用特殊的 npm Tag (default: "")
-  --packages <packages>    创建项目指定特定依赖版本信息 (default: "{}")
-  --registry <registry>    在创建过程中定制 npm Registry (default: "")
-  --no-need-install        无需安装依赖
-  -h, --help               display help for command
-
-Commands:
-  clean-cache              清除本地生成器缓存
-```
-
-下面将针对这些参数做详细介绍：
-
-## [projectDir]
-
-项目目录名称。
-
-执行 `@modern-js/create` 时，默认会在当前目录创建 `projectDir` 文件夹，并在该文件夹下初始化项目。该参数为空时，将会在当前目录直接生成初始化项目。
-
-:::info
-如果 `projectDir` 所在目录内容不为空，将会提示是否继续创建，推荐在空目录下进行项目初始化操作。
-:::
-
-## --version
-
-获取 `@modern-js/create` 工具版本。
-
-```bash
-npx @modern-js/create@latest --version
-
-[INFO] @modern-js/create v2.21.1
-```
-
-## --lang \<lang>
-
-执行执行语言，支持 `zh` 和 `en`。
-
-默认情况下，`@modern-js/create` 会自动识别用户的系统语言，选择使用中文或者英文，如果识别失败或者不符合使用习惯，可以使用该参数手动指定。
-
-## -c, --config \<config>
-
-指定项目默认配置。
-
-默认情况下，`@modern-js/create` 在执行过程中会出现选择语言、包管理工具等交互问题，当需要提前指定这些配置内容时，可以通过该字段传入。
-
-该字段为 JSON 字符串，例如需指定包管理工具时：
-
-```bash
-npx @modern-js/create@latest --config '{"packageManager": "pnpm"}'
-```
-
-`config` 支持的参数可查看[配置参数](/guides/topic-detail/generator/create/config.html)。
-
-## -d,--debug
-
-展示调试日志。
-
-当在使用过程中遇到问题时，可以使用该参数显示调试日志，方便快速定位问题位置及对问题进行排查。
-
-## --mwa
-
-快速创建 Web 应用项目。
-
-## --module
-
-快速创建 Npm 模块项目。
-
-## -p, --plugin \<plugin>
-
-指定生成器插件。
-
-`@modern-js/create` 支持使用生成器插件定制 Modern.js 默认的工程方案类型或者添加工程方案类型场景，详情可查看[开发生成器插件](/guides/topic-detail/generator/plugin/structure.html)。
-
-## --generator \<generator>
-
-指定微生成器。
-
-<!-- TODO 详情可查看[开发微生成器]-->
-`@modern-js/create` 支持使用微生成器完全定制项目生成流程。
-
-## --dist-tag \<distTag>
-
-指定生成器及 Modern.js 相关依赖版本。
-
-`@modern-js/create` 执行过程中会执行更小的微生成器，默认会使用 `latest` 的微生成器版本，使用该参数可以指定执行的微生成器的版本号和对应的安装 Modern.js 相关依赖的版本。
-
-比如使用 `next` 版本：
-
-```bash
-npx @modern-js/create@next --dist-tag next
-```
-
-## --packages \<packages>
-
-创建项目是指定特定包版本依赖。
-
-在创建项目时如果有需要指定特定包版本，可以使用该参数。该参数会在项目根目录的 `package.json` 中配置 `pnpm.overrides`(包管理工具选择 pnpm) 或者 `resolutions` 锁定包版本号。
-
-该参数值为 JSON 字符串。
-
-例如指定 react 版本：
-
-```bash
-npx @modern-js/create@latest --packages '{"react":"^17"}'
-```
-
-## --registry \<registry>
-
-指定执行子生成器和获取项目依赖版本的 npm registry。
-
-## --no-need-install
-
-忽略自动安装依赖。
-
-默认情况下，`@modern-js/create` 在创建项目完成后会自动安装依赖，使用该参数可以忽略安装依赖步骤。
-
-## clean-cache
-
-`@modern-js/create` 默认会在执行机器的 tmp 目录生成子生成器缓存用于加快生成器执行速度，在需要刷新缓存或者缓存出现问题时可以使用该命令删除缓存。
-
-```bash
-npx @modern-js/create@latest clean-cache
-```

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

@@ -1,48 +0,0 @@
----
-sidebar_position: 1
----
-
-# 使用
-
-Modern.js 提供了 `@modern-js/create` 工具用于创建 Modern.js 提供的工程方案项目，例如 [Web 应用](https://modernjs.dev/)、[Npm 模块](https://modernjs.dev/module-tools)。
-
-下面将介绍 `@modern-js/create` 的使用姿势。
-
-## 环境准备
-
-import Prerequisites from "@site-docs/components/prerequisites"
-
-<Prerequisites />
-
-## 使用 `@modern-js/create` 创建项目
-
-不需要全局安装 `@modern-js/create`，直接使用 npx 执行即可：
-
-```bash
-npx @modern-js/create@latest [projectDir]
-```
-
-:::info
-`[projectDir]` 为项目目录名称，不填写将会在当前目录创建项目。
-:::
-
-执行过程中需要根据提示完成交互，创建符合需求的项目。
-
-### 创建 Web 应用项目
-
-```bash
-npx @modern-js/create@latest web-app
-? 请选择你想创建的工程类型 Web 应用
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-```
-
-### 创建 Npm 模块项目
-
-```bash
-npx @modern-js/create@latest npm-module
-? 请选择你想创建的工程类型 Npm 模块
-? 请填写项目名称 npm-module
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-```

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

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