@modern-js/main-doc 2.21.0 → 2.22.0

package/docs/en/guides/advanced-features/bff/frameworks.mdx

@@ -6,7 +6,7 @@ title: Frameworks
 
 Modern.js's BFF supports different runtime frameworks, currently Modern.js's BFF supports two runtime frameworks[Express.js](https://expressjs.com/) 和 [Koa.js](https://koajs.com/).
 
-## Function Writing
+## Function Mode
 
 Under the function writing, only the middleware writing method of various runtime frameworks is different, and other implementations are basically the same. Take Express as an example to introduce how to write a middleware by hand in the `api/_ app.ts` and add permission verification:
 
@@ -96,7 +96,7 @@ Refresh the page and you can see that `/api/hello` was accessed successfully:
 
 The above code simulates the way to add middleware to the `/api/_app.ts` to achieve an easy login function. Also, other functions can be implemented in this hook file to extend BFF Server.
 
-## Framework Writing
+## Framework Mode
 
 Under the framework writing, Modern.js does not collect middleware in the `api/_app.ts`, and the running process is controlled by the plugin itself.
 

package/docs/en/guides/advanced-features/bff/function.mdx

@@ -51,10 +51,10 @@ Execute `pnpm run dev`, then open `http://localhost:8080/` to see that the page
 
 In Modern.js, the BFF function routing system is implemented based on the file system, and it is also a conventional routing system.
 
-In **Function Writing**, All files under `api/` will map to an interface. In **Framework Writing**, All files under `api/lambda` will map to an interface
+In **Function Mode**, All files under `api/` will map to an interface. In **Framework Mode**, All files under `api/lambda` will map to an interface
 
 :::note
-Function Writing & Framework Writing will introduce soon.
+Function Mode & Framework Mode will introduce soon.
 
 :::
 
@@ -69,14 +69,14 @@ Files named `index.[jt]s` are mapped to the previous directory.
 - `api/index.ts` -> `{prefix}/`
 - `api/user/index.ts` -> `{prefix}/user`
 
-### Multi-layer Route
+### Multi-layer Routing
 
 Supports parsing nested files, if you create a nested folder structure, the files will still automatically parse routes in the same way.
 
 - `api/hello.ts` -> `{prefix}/hello`
 - `api/user/list.ts` -> `{prefix}/user/list`
 
-### Dynamic Route
+### Dynamic Routing
 
 Create folders or files named with `[xxx]` to support dynamic named routing parameters.
 

package/docs/en/guides/advanced-features/bff/type.mdx

@@ -1,19 +1,19 @@
 ---
 sidebar_position: 2
-title: Writing Type
+title: BFF Type
 ---
-# Writing Type
+# BFF Type
 
 Runtime framework support is also an important part of **BFF**. Modern.js supports extending BFF's runtime framework through plugins, and provides a series of built-in plugins, developers can directly use the conventions and ecology of the framework.
 
-The plugin is compatible with most of the specifications of these frameworks, and each framework needs to provide two types of ways to extend the writing of BFF functions, namely **Function Writing** and **Framework Writing**.
+The plugin is compatible with most of the specifications of these frameworks, and each framework needs to provide two types of ways to extend the writing of BFF functions, namely **Function Mode** and **Framework Mode**.
 
 :::note
 Whether the current `api/` directory structure is written as a framework is determined by the corresponding plugin, Modern.js don't care.
 
 :::
 
-## Function Writing
+## Function Mode
 
 When the plugin considers that it is currently written as a function, it must support writing middleware in the `api/_ app.ts` to extend the BFF function.
 
@@ -32,7 +32,7 @@ The writing of middleware for different plugins is not the same, see [Runtime Fr
 
 :::
 
-## Framework Writing
+## Framework Mode
 
 Framework writing is a way of using frame structure to extend BFF functions. Compared with function writing, although frame writing can use more frame structure and make the entire BFF Server clearer in complex scenarios, it is also more complex and requires more attention to the content at the framework level.
 

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

@@ -30,14 +30,14 @@ 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`:
 
 ```bash
 $ pnpm run new
-? Action: Enable features
-? Enable features: Enable Rspack Build
+? Please select the operation you want: Enable features
+? Please select the feature name: Enable Rspack Build
 ```
 
 After executing the command, enable the Rspack build in `modern.config.ts`:
@@ -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/advanced-features/ssg.mdx

@@ -9,8 +9,8 @@ Static Site Generation is a solution for rendering complete static web pages at
 First need to execute `pnpm run new` to enable the SSG features:
 
 ```bash
-? Action Enable features
-? Enable features Enable SSG
+? Please select the operation you want: Enable features
+? Please select the feature name: Enable SSG
 ```
 
 After execute script, register SSG plugin in `modern.config.ts`:

package/docs/en/guides/advanced-features/testing.mdx

@@ -9,8 +9,8 @@ Modern.js integrates the testing capabilities of [Jest](https://jestjs.io/) by d
 First need to execute `pnpm run new` enable [unit test/integration test] features:
 
 ```
-? Action: Enable features
-? Enable features: Enable Unit Test / Integration Test
+? Please select the operation you want: Enable features
+? Please select the feature name: Enable Unit Test / Integration Test
 ```
 
 After executing the above command, the `"test": "modern test"` command will be automatically generated in package.json.

package/docs/en/guides/advanced-features/web-server.mdx

@@ -27,8 +27,8 @@ Because the full web server cannot be controlled this way, and the extension log
 You can execute the'pnpm run new 'command in the project root directory to enable the "Custom Web Serve" function:
 
 ```bash
-? Action Create project element
-? New "Custom Web Server" source code directory
+? Please select the operation you want: Create Element
+? Please select the type of element to create: New "Custom Web Server" source code directory
 ```
 
 After executing the command, register the `@modern-js/plugin-server` plugin in `modern.config.ts`:

package/docs/en/guides/basic-features/css.mdx

@@ -66,8 +66,8 @@ If you need to use other CSS-in-JS libraries such as [styled-jsx](https://www.np
 Follow the steps below to make a selection:
 
 ```bash
-? Action: Enable features
-? Enable features: Enable Tailwind CSS
+? Please select the operation you want: Enable features
+? Please select the feature name: Enable Tailwind CSS
 ```
 
 Register the Tailwind plugin in `modern.config.ts`:

package/docs/en/guides/basic-features/mock.mdx

@@ -32,7 +32,7 @@ export default {
   /* the default method is GET */
   '/api/getExample': { id: 1 },
 
-  /* You can use custom functions to dynamically return data */
+  /* You can use custom functions to dynamically return data, req and res are both Node.js HTTP objects. */
   'POST /api/addInfo': (req, res, next) => {
     res.setHeader('Access-Control-Allow-Origin', '*');
     res.end('200');

package/docs/en/guides/basic-features/proxy.mdx

@@ -6,7 +6,7 @@ sidebar_position: 5
 
 ## Local Proxy
 
-Modern.js provides a way to configure the development proxy in [tools.devServer](/configure/app/tools/dev-server). For example, to proxy the local interface to an online address:
+Modern.js provides a way to configure the development proxy in [`tools.devServer`](/configure/app/tools/dev-server). For example, to proxy the local interface to an online address:
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -25,11 +25,10 @@ export default defineConfig({
 });
 ```
 
-when access `http://localhost:8080/go/api`, the response content is returned from [http://www.example.com/](http://www.example.com/).
+When access `http://localhost:8080/go/api`, the response content will be returned from [http://www.example.com/](http://www.example.com/).
 
 :::info
 For more detail, see [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware).
-
 :::
 
 ## Global Proxy
@@ -40,7 +39,7 @@ import GlobalProxy from "@site-docs-en/components/global-proxy"
 
 ## BFF Proxy
 
-By configuring [`bff.proxy`](/configure/app/bff/proxy), you can proxy BFF API requests to specified services. Unlike other proxy above, it can also be used in the production environment:
+By configuring [`bff.proxy`](/configure/app/bff/proxy), BFF API requests can be proxied to a specified service. Unlike the other proxy methods above, it can be used in the production environment:
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -52,7 +51,7 @@ export default defineConfig({
 });
 ```
 
-For example, when a BFF call is used in the code, the final request `http://localhost:8080/api/v1/topics` will auto proxy to `https://cnodejs.org/api/v1/topics`:
+For example, when using BFF function in the code, the final request `http://localhost:8080/api/v1/topics` will be automatically proxied to `https://cnodejs.org/api/v1/topics`:
 
 ```js
 import getTopics from '@api/v1/topics';

package/docs/en/guides/basic-features/routes.mdx

@@ -182,7 +182,7 @@ Routes generated from file directories named with `[$]` will be treated as dynam
 
 The `routes/user/[id$]/page.tsx` file will be converted to the `/user/:id?` route. All routes under `/user` will match this route, and the `id` parameter is optional. This route is usually used to distinguish between **creation** and **editing**.
 
-In the component, you can use [useParams](/apis/app/runtime/router/router#useparams) to obtain the corresponding named parameter.
+In the component, you can use [useParams](/apis/app/runtime/router/router#useparams) to get the corresponding named parameter.
 
 In the loader, params will be passed as the input parameter of the [loader function](/guides/basic-features/data-fetch#loader-function), and you can get the parameter value through `params.xxx`.
 
@@ -191,7 +191,7 @@ In the loader, params will be passed as the input parameter of the [loader funct
 If you create a `$.tsx` file under the routes directory, it will be treated as the catch-all routing component. When there is no matching route, this component will be rendered.
 
 :::note
-`$.tsx` can be considered as a special `page` route component. When there is a `layout` component in the current directory, `$.tsx` will be rendered as a child component of `layout`.
+`$.tsx` can be considered as a special `page` route component. When there is a `layout.tsx` file in the current directory, `$.tsx` will be rendered as a child component of `layout`.
 :::
 
 For example, the following directory structure:
@@ -215,7 +215,7 @@ params['*']; // => 'aaa/bbb'
 
 ### No-path Layout
 
-When the directory name starts with `__`, the corresponding directory name will not be converted to an actual route path. For example, the following file directory:
+When the directory name starts with `__`, the directory name will not be converted to an actual route path. For example, the following file directory:
 
 ```bash
 .
@@ -449,7 +449,7 @@ However, this also brings a problem: if the chunk corresponding to the route has
 
 In this case, you can define a `Loading` component to display a custom `Loading` component before the static resources are loaded.
 
-To further improve the user experience and reduce loading time, Modern.js supports defining the `prefetch` attribute on the Link component to preload static resources and data. The `prefetch` attribute has three optional values:
+To further improve the user experience and reduce loading time, Modern.js supports defining the `prefetch` attribute on the Link component to preload static resources and data.
 
 ```tsx
 <Link prefetch="intent" to="page">
@@ -461,6 +461,8 @@ To further improve the user experience and reduce loading time, Modern.js suppor
 
 :::
 
+The `prefetch` attribute has three optional values:
+
 - `none`: default value, no prefetching, no additional behavior.
 - `intent`: This is the value we recommend for most scenarios. When you hover over the Link, the corresponding chunk and data defined in the data loader will be loaded automatically. When you move the mouse away, the loading will be cancelled automatically. In our tests, even fast clicks can reduce loading time by about 200ms.
 - `render`: The corresponding chunk and data defined in the Data Loader will be loaded when the Link component is rendered.
@@ -504,8 +506,6 @@ export default () => {
 Modern.js provides a series of optimizations for resource loading and rendering for conventional routing by default, and provides out-of-the-box SSR capabilities. When using self-controlled routing, developers need to encapsulate these capabilities themselves. It is recommended to use conventional routing.
 :::
 
-When using self-controlled routing, if the developer turns off the [`runtime.router`](/configure/app/runtime/router) configuration and uses `react-router-dom` directly, they also need to wrap it according to the React Router documentation.
-
 ## Other
 
 By default, Modern.js will enable the built-in routing scheme, which is React Router.
@@ -518,7 +518,9 @@ export default defineConfig({
 });
 ```
 
-Modern.js exposes the API of React Router from the `@modern-js/runtime/router` namespace for developers to use, ensuring that developers and Modern.js use the same code. In addition, in this case, the React Router code will be bundled into the JS output. If the project already has its own routing scheme or does not need to use client-side routing, this feature can be turned off.
+As mentioned above, when the [`runtime.router`](/configure/app/runtime/router) configuration is enabled, Modern.js will export the API of React Router from the `@modern-js/runtime/router` namespace for developers to use, ensuring that developers and Modern.js are using the same code, and automatically wrapping the `Provider` component according to the router configuration. In addition, in this case, the code of React Router will be packed into the JS output.
+
+If the project already has its own routing plan or does not need to use client-side routing, this feature can be disabled.
 
 ```js
 export default defineConfig({
@@ -527,3 +529,5 @@ export default defineConfig({
   },
 });
 ```
+
+As mentioned above, if the [`runtime.router`](/configure/app/runtime/router) configuration is disabled and `react-router-dom` is used directly for project routing management, the `Provider` needs to be wrapped according to the React Router documentation.

package/docs/en/guides/concept/entries.mdx

@@ -33,9 +33,9 @@ The project initialized by Modern.js is single-entry (SPA), and the project stru
 Modern.js can easily switch from single entry to multiple entry. You can execute `pnpm run new` under the project to create entry through generator:
 
 ```bash
-? Action: Create project element
-? Create project element: New "entry"
-? Entry name: new-entry
+? Please select the operation you want: Create Element
+? Please select the type of element to create: New "entry"
+? Please fill in the entry name: new-entry
 ```
 
 After execution, Modern.js will automatically generate a new entry directory, and you can see that the `src/` directory has the following structure:

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
+}