@modern-js/main-doc 2.60.6 → 2.62.0

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"]

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

@@ -1,116 +0,0 @@
----
-sidebar_position: 3
----
-
-# 配置参数
-
-`new` 命令提供了 [--config](/guides/topic-detail/generator/new/option.html#-c,---config-<config>) 参数，用于提前指定执行过程中交互问题的答案。
-
-这里将介绍不同情况下，可以在 `config` 中配置的字段及字段值。
-
-## 通用配置
-
-### actionType
-
-问题：请选择你想要的操作
-
-选项：
-
-- 创建工程元素 -- element
-
-- 启用可选功能 -- function
-
-- 自动重构 -- refactor
-
-## Web 应用
-
-### element
-
-问题：请选择创建元素类型
-
-选项：
-
-- 新建「应用入口」 -- entry
-
-- 新建「自定义 Web Server」源码目录 -- server
-
-### name
-
-问题： 请填写入口名称
-
-:::info
-新建应用入口时需要该配置，该配置值为字符串类型。
-:::
-
-### function
-
-问题：请选择功能名称
-
-选项：
-
-- 启用「Rspack 构建」 -- rspack
-
-- 启用 「Tailwind CSS」 支持 -- tailwindcss
-
-- 启用「BFF」功能 -- bff
-
-- 启用「SSG」功能 -- ssg
-
-- 启用「SWC 编译」-- swc
-
-- 启用「微前端」模式 -- micro_frontend
-
-- 启用「基于 UA 的 Polyfill」功能 -- polyfill
-
-- 启用「全局代理」 -- proxy
-
-
-### bffType
-
-问题：请选择 BFF 类型
-
-选项：
-
-- 函数模式 -- func
-
-- 框架模式 -- framework
-
-:::info
-启用 BFF 功能时需要该配置。
-:::
-
-### framework
-
-问题：请选择运行时框架
-
-选项：
-
-- Express -- express
-
-- Koa -- koa
-
-:::info
-启用 BFF 功能时需要该配置。
-:::
-
-### refactor
-
-问题：请选择重构类型
-
-选项：
-
-- 使用 React Router v5 -- react_router_5
-
-## Npm 模块
-
-### function
-
-问题：启用可选功能
-
-选项：
-
-- 启用 「Tailwind CSS」 支持 -- tailwindcss
-
-- 启用「Storybook」 -- storybook
-
-- 启用「Runtime API」 -- runtime_api

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

@@ -1,67 +0,0 @@
----
-sidebar_position: 2
----
-
-# CLI 参数
-
-`new` 命令提供了很多配置参数用于配置其执行过程中的行为，可以通过 `--help` 参数进行查看：
-
-```bash
-npm run new --help
-
-Usage: modern new [options]
-
-启用可选功能
-
-Options:
-  --lang <lang>          设置 new 命令执行语言(zh 或者 en)
-  -c, --config <config>  生成器运行默认配置(JSON 字符串)
-  -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
-  --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
-  --registry <registry>  生成器运行过程中定制 npm Registry
-  -h, --help             display help for command
-```
-
-下面将针对这些参数做详细介绍：
-
-## --lang \<lang>
-
-执行执行语言，支持 `zh` 和 `en`。
-
-默认情况下，`new` 命令会自动识别用户的系统语言，选择使用中文或者英文，如果识别失败或者不符合使用习惯，可以使用该参数手动指定。
-
-## -c, --config \<config>
-
-指定项目默认配置。
-
-默认情况下，new 命令在执行过程中会出现选择操作类型、开启功能等交互问题，当需要提前指定这些配置内容时，可以通过该字段传入。
-
-该字段为 JSON 字符串，例如需指定 BFF 框架时：
-
-```bash
-npm run new --config '{"framework": "express"}'
-```
-
-`config` 支持的参数可查看[配置参数](/guides/topic-detail/generator/new/config.html)。
-
-## -d,--debug
-
-展示调试日志。
-
-当在使用过程中遇到问题时，可以使用该参数显示调试日志，方便快速定位问题位置及对问题进行排查。
-
-## --registry \<registry>
-
-指定执行子生成器和获取项目依赖版本的 npm registry。
-
-## --dist-tag \<distTag>
-
-指定生成器版本。
-
-`new` 命令执行过程中会执行更小的微生成器，默认会使用 `latest` 的微生成器版本，使用该参数可以指定执行的微生成器的版本号的版本。
-
-比如使用 `next` 版本：
-
-```bash
-npm run new --dist-tag next
-```

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

@@ -1,74 +0,0 @@
----
-sidebar_position: 1
----
-
-# 使用
-
-在 Web 应用、 Npm 模块中，我们提供了 `new` 命令用于创建项目元素、开启功能和创建子项目。
-
-## Web 应用
-
-Web 应用项目通过 `@modern-js/app-tools` 提供 `new` 命令。
-
-new 命令提供了三种操作类型：
-
-- 创建工程元素
-
-- 启用可选功能
-
-- 自动重构
-
-每种操作类型都提供了对应支持的列表，可根据项目情况进行选择。
-
-例如：
-
-创建新的应用入口：
-
-```bash
-npm run new
-? 请选择你想要的操作 创建工程元素
-? 请选择创建元素类型 新建「应用入口」
-? 请填写入口名称 entry
-```
-
-执行完成后将会在项目 `src` 目录创建新入口对应名称的文件夹及默认入口文件，并且自动帮忙整理之前 `src` 下入口文件到 `package.json` 中 `name` 字段对应的文件夹中。
-
-开启 BFF 功能：
-
-```bash
-npm run new
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「BFF」功能
-? 请选择 BFF 类型 函数模式
-? 请选择运行时框架 Express
-```
-
-执行完成后将会在项目安装 BFF 相关依赖，并创建 api 目录用于 BFF 模块的开发并提供提示信息用于注册 BFF 插件。
-
-:::info
-这里未帮助用户自动注册插件，原因是由于 `modern.config.[tj]s` 在项目生命周期中变化比较复杂，可能存在模块之间互相引用问题，让用户手动注册能保证修改配置的正确性。
-
-在后续定制化的开发中，如果有类似的需求，也可以通过提示的方式给到使用方操作指南，让用户对文件进行手动操作。
-:::
-
-:::warning
-执行 new 命令时可能会出现需要开启的功能不在列表中，需要检查一下项目 `package.json` 中是否已经安装对应功能的插件，如果仍需使用 new 命令开启，需要先手动移除对应的插件依赖。
-:::
-
-## Npm 模块
-
-Npm 模块项目通过 `@modern-js/module-tools` 提供 new 命令。
-
-new 命令提供了启用可选功能的能力。
-
-例如：
-
-开启 Storybook 能力：
-
-```bash
-npm run new
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「Storybook」
-```
-
-执行完成后将会在项目安装 Storybook 插件相关依赖，增加 `storybook` 命令，创建 `stories` 目录用于 Storybook 模块的开发并提供提示信息用于注册 Storybook 插件。

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

@@ -1,11 +0,0 @@
-[
-  "structure",
-  "category",
-  "use",
-  "context",
-  {
-    "type": "dir",
-    "name": "api",
-    "label": "API"
-  }
-]