@modern-js/main-doc 0.0.0-next-1685502535286 → 0.0.0-next-1685530921784

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @modern-js/main-doc
 
-## 0.0.0-next-1685502535286
+## 0.0.0-next-1685530921784
 
 ### Minor Changes
 
@@ -16,7 +16,7 @@
 
 - Updated dependencies [850cde6673]
 - Updated dependencies [e7a5f9443b]
-  - @modern-js/builder-doc@0.0.0-next-1685502535286
+  - @modern-js/builder-doc@0.0.0-next-1685530921784
 
 ## 2.21.1
 

package/docs/en/components/language-config.mdx

@@ -0,0 +1,9 @@
+### language
+
+Question: Please select the programming language.
+
+Options:
+
+- TS -- ts
+
+- ES6+ -- js

package/docs/en/components/package-manager.mdx

@@ -0,0 +1,11 @@
+### packageManager
+
+Question: Please select the package manager.
+
+Options:
+
+- pnpm -- pnpm
+
+- Yarn -- yarn
+
+- npm -- npm

package/docs/en/guides/advanced-features/rspack-start.mdx

@@ -30,7 +30,7 @@ When using Rspack as the bundler, the following Features are temporarily unavail
 
 :::
 
-## Migrating from webpack to Rspack
+## Enable Rspack build
 
 You can enable Rspack build by running `pnpm run new`:
 
@@ -54,9 +54,9 @@ import appTools, { defineConfig } from '@modern-js/app-tools';
 });
 ```
 
-:::tip
-When migrating from webpack to Rspack, there may have some differences in build and configuration capabilities. For more details, please refer to [Configuration Differences](https://modernjs.dev/builder/en/guide/advanced/rspack-start.html#migrating-from-webpack-to-rspack).
-:::
+## Migrating configuration
+
+After enabling Rspack building capability, further configuration migration is needed by referring to the [Configuration Differences](https://modernjs.dev/builder/en/guide/advanced/rspack-start.html#migrating-from-webpack-to-rspack).
 
 ## The relationship between Rspack and Modern.js versions
 

package/docs/en/guides/topic-detail/generator/create/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "@modern-js/create",
+  "position": 1
+}

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

@@ -0,0 +1,75 @@
+---
+sidebar_position: 3
+---
+
+# Configuration Parameters
+
+`@modern-js/create` provides the [--config](/guides/topic-detail/generator/create/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
+
+### solution
+
+Question: Please select the type of project you want to create.
+
+Options:
+
+- Web App -- mwa
+
+- Npm Module -- module
+
+- Doc Site -- doc
+
+- Monorepo -- monorepo
+
+### scenes
+
+Question: Please select the project scenario.
+
+Options:
+
+List of plugin keywords when using custom generator plugins.
+
+## Web App
+
+import LanguageConfig from '@site-docs-en/components/language-config';
+
+<LanguageConfig />
+
+import PackageManager from '@site-docs-en/components/package-manager';
+
+<PackageManager />
+
+### buildTools
+
+Question: Please select the bundler.
+
+Options:
+
+- webpack -- webpack
+
+- Rspack -- rspack
+
+## Npm Module
+
+### packageName
+
+Question: Please fill in the project name.
+
+:::info
+The value of the `name` field in the `package.json` file of the Npm module, which is a string type.
+:::
+
+<LanguageConfig />
+
+<PackageManager />
+
+## Modern Doc
+
+<PackageManager />
+
+## Monorepo
+
+<PackageManager />

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

@@ -0,0 +1,151 @@
+---
+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)
+  --monorepo               create monorepo 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 management tools 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 management tool:
+
+```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.
+
+## --monorepo
+
+Quickly create a Monorepo 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 management tool 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

@@ -0,0 +1,66 @@
+---
+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), [Modern Doc](https://modernjs.dev/doc-tools), [Monorepo](/guides/topic-detail/monorepo/intro.html).
+
+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
+? Please select the bundler: webpack
+```
+
+### 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
+```
+
+### Create a Modern Doc Project
+
+```bash
+npx @modern-js/create@latest doc-website
+? Please select the type of project you want to create: Doc Site
+? Please select the package manager: pnpm
+```
+
+### Create Monorepo Project
+
+```bash
+npx @modern-js/create@latest monorepo
+? Please select the type of project you want to create: Doc Site
+? Please select the package manager: pnpm
+```
+

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

@@ -0,0 +1,4 @@
+{
+  "label": "new Command",
+  "position": 2
+}

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

@@ -0,0 +1,155 @@
+---
+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 Unit Test / Integration Test -- test
+
+- Enable UA-based Polyfill Feature -- polyfill
+
+- Enable Global Proxy -- proxy
+
+- Enable Visual Testing (Storybook) -- mwa_storybook
+
+### 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 Unit Test / Integration Test -- test
+
+- Enable Tailwind CSS -- tailwindcss
+
+- Enable Storybook -- storybook
+
+- Enable Runtime API -- runtime_api
+
+## Monorepo
+
+### sub_solution
+
+Question: Please select the type of project you want to create.
+
+Options:
+
+- Web App -- mwa
+
+- Web App (Test)-- mwa_test
+
+- Npm Module -- module
+
+- Npm Module (Inner) -- inner_module
+
+### packageName
+
+Question: Please fill in the project name
+
+:::info
+The value of the `name` field in the `package.json` file of the sub-project, which is a string type.
+
+:::
+
+### packagePath
+
+Question: Please fill in the sub-project directory name
+
+:::info
+The name of the subdirectory in the `apps` or `packages` directory on which the sub-project is based, which is a string type.
+
+:::

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

@@ -0,0 +1,67 @@
+---
+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

@@ -0,0 +1,95 @@
+---
+sidebar_position: 1
+---
+
+# Usage
+
+In Web App, Npm Module and Monorepo 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.
+
+## Monorepo
+
+Monorepo projects use the `new` command provided by `@modern-js/monorepo-tools`.
+
+The `new` command provides the ability to create sub-project.
+
+For example:
+
+Create Web App Sub-project:
+
+```bash
+? Please select the type of project you want to create: Web App
+? Please fill in the sub-project name: web_app
+? Please fill in the sub-project directory name: web_app
+? Please select the programming language: TS
+? Please select the bundler: webpack
+```
+
+After running, a sub-project named `web_app` will be created in the `apps` directory of the project. In the sub-project directory, you can still run the `new` command to create project elements and enable features.

package/docs/en/guides/topic-detail/generator/plugin/_category_.json

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

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

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