@modern-js/main-doc 2.21.1 → 2.22.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @modern-js/main-doc
 
+## 2.22.0
+
+### Minor Changes
+
+- 7d1b96e: feat(changeset): optimize release note display
+
+  feat(changeset): 优化生成 Release Note 文案
+
+### Patch Changes
+
+- 3c3d1e2: docs: update project creation and new command text.
+
+  docs: 更新生成器创建项目和 new 命令文案。
+
+- Updated dependencies [850cde6]
+- Updated dependencies [e7a5f94]
+  - @modern-js/builder-doc@2.22.0
+
 ## 2.21.1
 
 ### Patch Changes

package/docs/en/apis/app/commands.mdx

@@ -125,9 +125,9 @@ In the project, execute the `new` command to add entries as follows:
 
 ```bash
 $ npx modern new
-? Action Create project element
-? Create project element New "entry"
-? Entry name 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: entry
 ```
 
 ### Enable Features
@@ -136,8 +136,8 @@ In the project, execute the `new` command to enable features as follows:
 
 ```bash
 $ npx modern new
-? Action Enable features
-? Enable features (Use arrow keys)
+? Please select the operation you want: Enable features
+? Please select the feature name: (Use arrow keys)
 ❯ Enable Tailwind CSS
   Enable BFF
   Enable SSG

package/docs/en/apis/app/hooks/api/api.mdx

@@ -0,0 +1,80 @@
+---
+title: '**/*.[tj]s'
+sidebar_position: 1
+---
+# **/*.[tj]s
+
+Files that declare API routes in the [BFF Function Mode](/guides/advanced-features/bff/type.html#function-mode). Except for some [convention files](/apis/app/hooks/api/api#allow-list), files in the `api` directory will be registered as the routes.
+
+:::info
+Using the `api` directory requires enabling the BFF feature, and you need to run the `new` command in the project to enable the "BFF" feature.
+
+This file supports using the `js` or `ts` language, but you must use `esm` syntax to export functions.
+
+:::
+
+## Routing File Convention
+
+### Default Routing
+
+The routing system will map files named `index` to the previous directory.
+
+- `api/index.ts` -> `$BASENAME/`
+- `api/user/index.ts` -> `$BASENAME/user`
+
+### Nested Routing
+
+The routing system also supports parsing nested files. If you create a nested folder structure, the files will still automatically resolve routes in the same way.
+
+- `api/hello.ts` -> `$BASENAME/hello`
+- `api/user/list.ts` -> `$BASENAME/user/list`
+
+### Dynamic Routing
+
+The routing system supports generating dynamic routes through file directories named with `[]`.
+
+- `api/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
+- `api/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
+- `api/article/[id]/info.ts` -> `$BASENAME/article/:id/info`
+
+The `$BASENAME` can be configured in `modern.config.js`, and the default value is `/api`.
+
+### Allow List
+
+By default, all files in the `api` directory will be parsed as BFF function files, but we also set a white list for these files that are not parsed:
+
+- Files whose names start with `_`. For example: `_utils.ts`.
+- All files in folders whose names start with `_`. For example: `_utils/index.ts`, `_utils/cp.ts`.
+- Test files. For example: `foo.test.ts`.
+- TypeScript type files. For example: `hello.d.ts`.
+- Files under `node_modules`.
+
+## Function Definition
+
+In addition to the routing rules above, there are also conventions for function definitions and exports in the code.
+
+Functions are exported by name, and the name of the exported function is the HTTP method accepted by the corresponding interface, that is:
+
+```ts
+export const get = async () => {
+  return {
+    name: 'Modern.js',
+    desc: 'Modern web Solutions',
+  };
+};
+```
+
+By exporting functions in this way, you will get a `GET` interface.
+
+The application project supports 9 Method definitions, namely: `GET`, `POST`, `PUT`, `DELETE`, `CONNECT`, `TRACE`, `PATCH`, `OPTION`, `HEAD`, that is, these Methods can be used as the names of the exported functions.
+
+The name is case-insensitive, that is, if it is `GET`, it can be written as `get`, `Get`, `GEt`, `GET`, all of which can be accurately recognized. The default export, that is, `export default xxx`, will be mapped to `Get`.
+
+Because `delete` is a keyword in JavaScript, you can use `del` or `DELETE` instead.
+
+Multiple functions with different Methods can be defined in one file, but if multiple functions with the same Method are defined, only the first one will take effect.
+
+:::info
+It should be noted that the defined functions should all be asynchronous, which is related to the type when calling the function.
+
+:::

package/docs/en/apis/app/hooks/api/app.mdx

@@ -0,0 +1,12 @@
+---
+title: _app.[tj]s
+sidebar_position: 2
+---
+# _app.[tj]s
+
+In the [BFF Function Mode](/guides/advanced-features/bff/type.html#function-mode), this file can add pre-middleware for BFF functions.
+
+:::note
+For specific examples, please refer to [hook](/apis/app/runtime/bff/hook).
+
+:::

package/docs/en/apis/app/hooks/api/lambda.mdx

@@ -0,0 +1,57 @@
+---
+title: lambda/*.[tj]s
+sidebar_position: 3
+---
+# lambda/*.[tj]s
+
+Files that declare API routes under the [BFF Framework Mode](/guides/advanced-features/bff/type.html#framework-mode). Except for [convention files](/apis/app/hooks/api/api#allow-list), files under the `lambda/` directory will be registered as the routes.
+
+:::info
+Using the `api` directory requires enabling the BFF function, and you need to run the new command to enable the "BFF" function under the project.
+
+:::
+
+:::tip
+This file supports using `js` or `ts` language, but must export functions using `esm` syntax.
+
+:::
+
+## Routing File Convention
+
+### Default Routing
+
+The routing system will map files named `index` to the previous directory.
+
+- `api/lambda/index.ts` -> `$BASENAME/`
+- `api/lambda/user/index.ts` -> `$BASENAME/user`
+
+### Nested Routing
+
+The routing system also supports parsing nested files. If you create a nested folder structure, the files will still automatically resolve routes in the same way.
+
+- `api/lambda/hello.ts` -> `$BASENAME/hello`
+- `api/lambda/user/list.ts` -> `$BASENAME/user/list`
+
+### Dynamic Routing
+
+The routing system supports generating dynamic routes through file directories named with `[]`.
+
+- `api/lambda/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
+- `api/lambda/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
+- `api/lambda/article/[id]/info.ts` -> `$BASENAME/article/:id/info`
+
+The `$BASENAME` can be configured in `modern.config.js`, and the default value is `/api`.
+
+### Allow List
+
+By default, all files in the `lambda` directory are parsed as BFF function files, but we also set up a whitelist so that these files are not parsed:
+
+- Files named starting with `_`. For example: `_utils.ts`.
+- All files in a folder named starting with `_`. For example: `_utils/index.ts`, `_utils/cp.ts`.
+- Test files. For example: `foo.test.ts`.
+- TypeScript type files. For example: `hello.d.ts`.
+- Files under `node_module`.
+
+## Function Definition
+
+Completely consistent with the [Function Definition](/apis/app/hooks/api/api#function-definition) under the function mode.

package/docs/en/apis/app/hooks/api/test.mdx

@@ -1,6 +1,6 @@
 ---
 title: test.[tj]s
-sidebar_position: 2
+sidebar_position: 4
 ---
 
 # test.[tj]s

package/docs/en/apis/app/hooks/config/html.mdx

@@ -4,6 +4,6 @@ sidebar_position: 1
 ---
 # html/
 
-The `config/html` directory allows you to inject custom html snippets in different places in the default html template.
+You can inject custom HTML fragments at different locations of the default internal HTML template through the `config/html` directory.
 
-For detail, see [HTML](/guides/basic-features/html).
+For specific usage, please refer to: [Custom HTML](/guides/basic-features/html).

package/docs/en/apis/app/hooks/config/icon.mdx

@@ -1,20 +1,20 @@
 ---
-title: icon
+title: icon/
 sidebar_position: 2
 ---
 
-# Icon
+# icon/
 
-## Set favicon
+## Favicon
 
-When there is a `favicon.*` file in the `config` directory of the project root directory, Modern.js will automatically set the file to the [html.favicon](/configure/app/html/favicon) config to generate the favicon icon for the page:
+When there is a `favicon.*` file in the `config` directory at the root of the project, Modern.js will automatically set the file to the [html.favicon](/configure/app/html/favicon) configuration item for generating the favicon icon on the page:
 
 ```
 ./config
 └── favicon.ico
 ```
 
-After the build is complete, you can see that the following tags are automatically generated in the HTML:
+After the build is completed, you can see the following tags automatically generated in HTML:
 
 ```html
 <link rel="icon" href="/favicon.ico" />
@@ -24,22 +24,22 @@ After the build is complete, you can see that the following tags are automatical
 
 When setting up the favicon, Modern.js looks for files in the following order:
 
-- favicon.png
-- favicon.jpg
-- favicon.jpeg
-- favicon.svg
-- favicon.ico
+- `favicon.png`
+- `favicon.jpg`
+- `favicon.jpeg`
+- `favicon.svg`
+- `favicon.ico`
 
-## Set app icon
+## Apple Touch Icon
 
-When there is an `icon.*` file in the `config` directory of the project root directory, Modern.js will automatically set the file to the [html.appIcon](/configure/app/html/app-icon) config, it is used to generate the apple-touch-icon icon for the iOS system.
+When there is an `icon.*` file in the `config` directory at the root of the project, Modern.js will automatically set the file to the [html.appIcon](/configure/app/html/app-icon) configuration item for generating the Apple Touch Icon icon under the iOS system.
 
 ```
 ./config
 └── icon.png
 ```
 
-After the build is complete, you can see that the following tags are automatically generated in the HTML:
+After the build is completed, you can see the following tags automatically generated in HTML:
 
 ```html
 <link rel="apple-touch-icon" sizes="180*180" href="/static/image/icon.png" />
@@ -47,10 +47,10 @@ After the build is complete, you can see that the following tags are automatical
 
 ### Order
 
-When setting the app icon, Modern.js looks for files in the following order:
+When setting up the app icon, Modern.js looks for files in the following order:
 
-- icon.png
-- icon.jpg
-- icon.jpeg
-- icon.svg
-- icon.ico
+- `icon.png`
+- `icon.jpg`
+- `icon.jpeg`
+- `icon.svg`
+- `icon.ico`

package/docs/en/apis/app/hooks/config/mock.mdx

@@ -4,4 +4,4 @@ sidebar_position: 5
 ---
 # mock/
 
-when `config/mock/index.js` exist, Modernjs auto start the Mock service in the development.
+When there is a `config/mock/index.js` file in the project directory, Modern.js will automatically enable the Mock service during development.

package/docs/en/apis/app/hooks/config/public.mdx

@@ -4,27 +4,27 @@ sidebar_position: 3
 ---
 # public/
 
-Static resource files in any format can be placed in the `public/`, and the files will be Served under the web application domain name.
+Any static resource files can be placed in the `public/` directory, and the files will be deployed to the corresponding application domain by the server.
 
 ## Description
 
-The routing of files to be served is based on the convention of the file system. `public/` is the root directory, which corresponds to the root path of the Web application.
+The file routing is based on the convention of the directory structure, where `public/` is the root directory corresponding to the root path of the Web application.
 
-For example, the `config/public/sdk/index.js` file will be Served under `${domain}/sdk/index.js` after deployment.
+For example, the `config/public/sdk/index.js` file will be deployed under `${domain}/sdk/index.js` after deployment.
 
-## Scene
+## Scenarios
 
-For example, `robots.txt`, `auth.xml` and other authentication file.
+For example, authentication files required by third-party systems such as `robots.txt` and `auth.xml`.
 
-SDK (requiring the same routing) for other business, or an HTML file for static host.
+Or SDKs for other business parties (requiring unchanged routing), or HTML files without entry.
 
 :::info
-For static resources (such as SVG pictures) that need to be referenced by import in the source code, it is recommended to put them in the `src/assets/` for management.
+For static resources (such as SVG images) that need to be imported through import in the source code, it is recommended to manage them in the `src/assets` directory.
 
 :::
 
-## Compression
+## Code Compression
 
-If the file is a `.js` file, it will be automatically compressed when the production environment is built.
+If the file in the directory is a `.js` file, it will be automatically compressed during production environment construction.
 
-If the file ends with `.min.js`, it will not compression.
+If the file ends with `.min.js`, it will not be compressed.

package/docs/en/apis/app/hooks/config/storybook.mdx

@@ -4,11 +4,11 @@ sidebar_position: 7
 ---
 # storybook/
 
-Modern.js.js supports debugging with Storybook. When you need to configure Storybook, configure it in the `config/storybook/`.
+Modern.js supports debugging using Storybook. When configuring Storybook, you need to configure it in the `config/storybook` directory of the project.
 
-For detail, see [Storybook](https://storybook.js.org/docs/react/configure/overview).
+Please refer to [Storybook Configuration](https://storybook.js.org/docs/react/configure/overview) for Storybook configuration.
 
 :::info
-Debugging with Storybook requires executing the `new` command to enable the 「Visual Testing (Storybook)」 mode feature.
+Enabling the Visual Testing (Storybook) mode function requires running the new command to enable it under the project first.
 
 :::

package/docs/en/apis/app/hooks/config/upload.mdx

@@ -4,29 +4,29 @@ sidebar_position: 4
 ---
 # upload/
 
-Static resource files in any format can be placed in the `upload/`.
+Any static resource files can be placed in the `upload/` directory.
 
 ## Description
 
-In the development environment, the static resource files in this directory will be hosted in the '/upload' path. After building the application product, the files in this directory will be copied to the dist path.
+In the development environment, the static resource files in this directory will be hosted under the `/upload` path. After building the application, the files in this directory will be copied to the dist directory.
 
-This file convention is mainly used for developers to use plugins to upload static resource files to the CDN.
+This file convention is mainly used for developers to use plugins to proactively upload static resource files to the CDN.
 
-## Scene
+## Scenarios
 
-For example, the SDK used by the project such as `google-analysis.js` (usually requires http caching).
+For example, SDKs for project use only, such as `google-analysis.js` (usually requires HTTP caching).
 
-Images, font files, generic CSS, etc.
+Pictures, font files, common CSS, etc.
 
-## Compression
+## Code Compression
 
-If the file is a `.js` file, it will be automatically compressed when the production environment is built.
+If the file in the directory is a `.js` file, it will be automatically compressed during production environment construction.
 
-If the file ends with `.min.js`, it will not compression.
+If the file ends with `.min.js`, it will not be compressed.
 
 ## More Usage
 
-In React components, this prefix can be added via [built-in environment variables](/guides/basic-features/env-vars.html#asset_prefix):
+In React components, you can add this prefix through [Environment Variables](/guides/basic-features/env-vars.html#asset_prefix):
 
 ```tsx
 export default () => {
@@ -36,19 +36,19 @@ export default () => {
 };
 ```
 
-Whether in [custom HTML](/guides/basic-features/html), or in any HTML file under ['config/public/'](/apis/app/hooks/config/public), you can directly use the HTML tag to refer to the resources in the `config/upload/`:
+In addition, whether it is in [Custom HTML](/guides/basic-features/html) or any HTML file under [`config/public/`](/apis/app/hooks/config/public), you can directly use HTML tags to reference resources in the `config/upload/` directory:
 
 ```html
 <script src="/upload/index.js"></script>
 ```
 
-if [`output.assetPrefix`](/configure/app/output/asset-prefix) is configured, add this prefix directly using template syntax:
+If you set the [`dev.assetPrefix`](/configure/app/dev/asset-prefix) or [`output.assetPrefix`](/configure/app/output/asset-prefix) prefix, you can also use template syntax to add the prefix directly:
 
 ```html
 <script src="<%=assetPrefix %>/upload/index.js"></script>
 ```
 
 :::info
-Modern.js does not support the use files under `upload/` in `config/public/*.css` via URL.
+Modern.js does not support using files under `config/upload/` through URLs in `config/public/*.css` (such as background-image).
 
 :::

package/docs/en/apis/app/hooks/modern-config.mdx

@@ -1,9 +1,9 @@
 ---
-title: modern.config.js
+title: modern.config.[tj]s
 sidebar_position: 8
 ---
-# modern.config.js
+# modern.config.[tj]s
 
-Modern.js config file, through which you can confiured all aspects of the current project.
+The Modern.js configuration file. Through this file, you can personalize the configuration of various aspects of the current project.
 
-For detail, see [configure](/configure/app/usage).
+To learn more about how to use the configuration, please refer to [Configuration Usage](/configure/app/usage).

package/docs/en/apis/app/hooks/server/index_.mdx

@@ -5,13 +5,6 @@ sidebar_position: 1
 
 # index.[tj]s
 
-A file that extends the Modern.js Web Server, to add a Hook or Middleware to the Web Server that the project uses.
+A file that extends the Modern.js Web Server. You can add [Hooks](/apis/app/runtime/web-server/hook) or [Middleware](/apis/app/runtime/web-server/middleware) to the Web Server started by the application project in this file.
 
-It can intercept requests and responses, authenticate and role, request preprocessing, exception bottom-up, etc.;
-
-It can also be inserted logic into the built-in processing handler (including route matching, resource addressing, header injection, page rendering, static web hosting).
-
-:::info
-For detail, see [Hook](/apis/app/runtime/web-server/hook) & [Middleware](/apis/app/runtime/web-server/middleware).
-
-:::
+You can intercept and process requests and responses, perform authentication and role verification, preprocess requests, and catch exceptions. You can also insert specific business logic into the built-in processing logic (including route matching, resource addressing, header injection, page rendering, and static web hosting).

package/docs/en/apis/app/hooks/server/test.mdx

@@ -2,11 +2,14 @@
 title: test.[tj]s
 sidebar_position: 2
 ---
+
 # test.[tj]s
 
-App's Web Server test file, support for writing test cases in the `server/` directory which file with suffix `.test.[tj]s`.
+Custom Web Server test directory.
+
+The application supports testing custom Web Server. You can directly create files with the suffix `.test.[tj]s` under the `server/` directory of the project to write test cases.
 
 :::info
-To use unit test and integration test, you need to execute the `new` command in advance to enable the `unit test/integration test`.
+Enabling unit testing and integration testing requires running the `new` command to enable the "Unit Testing/Integration Testing" function under the project first.
 
 :::

package/docs/en/apis/app/hooks/shared.mdx

@@ -4,4 +4,4 @@ sidebar_position: 5
 ---
 # shared/
 
-Shared directory. When the project has common code under `api/`, `server/`, `src/`, put the code under this directory rather then import directly.
+Shared source code directory. When there is common code in `api/`, `server/`, and `src/` in the project, you can put these codes in the `shared` directory instead of directly referencing them.

package/docs/en/apis/app/hooks/src/app.mdx

@@ -4,51 +4,41 @@ sidebar_position: 1
 ---
 # App.[tj]sx
 
-Entry identifier if App want control route by code.
+The identifier for the entry points when the application uses [Self-controlled Routing](/guides/basic-features/routes.html#self-controlled-routing).
 
-`App.[tj]sx` is not the actual App entry, Modern.js will auto generate the entry file, the content is roughly as follows:
+`App.[tj]sx` is not the actual entry. Modern.js will generate the real entry for application. The content is roughly as follows:
 
 ```js
 import React from 'react';
+import ReactDOM from 'react-dom/client';
 import { createApp, bootstrap } from '@modern-js/runtime';
 // App.[jt]sx
 import App from '@_modern_js_src/App';
-import { state } from '@modern-js/runtime/plugins';
-import {
-  immer,
-  effects,
-  autoActions,
-  devtools,
-} from '@modern-js/runtime/model';
-
-const createStatePlugins = config => {
-  const plugins = [];
-  plugins.push(immer(config['immer']));
-  plugins.push(effects(config['effects']));
-  plugins.push(autoActions(config['autoActions']));
-  plugins.push(devtools(config['devtools']));
-  return plugins;
-};
+// runtime plugin
+import { router } from '@modern-js/runtime/plugins';
+
+const IS_BROWSER = typeof window !== 'undefined' && window.name !== 'nodejs';
+const MOUNT_ID = 'root';
+
 let AppWrapper = null;
+
 function render() {
   AppWrapper = createApp({
     plugins: [
-      state({
-        ...{ plugins: createStatePlugins(true) },
-        ...App?.config?.state,
-      }),
-    ],
-  })(App);
+     router({...{"serverBase":["/"]}, ...App.config?.router}),
+    ]
+  })(App)
   if (IS_BROWSER) {
-    bootstrap(AppWrapper, MOUNT_ID);
+    bootstrap(AppWrapper, MOUNT_ID, null, ReactDOM);
   }
-  return AppWrapper;
+  return AppWrapper
 }
+
 AppWrapper = render();
 export default AppWrapper;
 ```
 
 :::note
-In multi-entry App, each entry can have a `App.[jt]sx`, for detail, see [Entry](/guides/concept/entries).
+In the multi-entry scenario, each entry can have its own `App.[jt]sx`. See [Entries](/guides/concept/entries) for details.
 
 :::

package/docs/en/apis/app/hooks/src/index_.mdx

@@ -4,13 +4,13 @@ sidebar_position: 4
 ---
 # index.[tj]s
 
-Entry identifier if App want use custom bootstrap. In most case, [`App.[tj]sx`](/apis/app/hooks/src/app) hook file can already meet our needs.
+The identifier for the entry point when the application uses custom `bootstrap`.
 
-When we need to add custom behavior before `bootstrap` or completely take over the webpack entry, we can place `index.[tj]s` in `src/` or entry directory. The following are discussed in two cases:
+In general, the [`App.[tj]sx`](/apis/app/hooks/src/app) hook file can already meet our needs. When we need to add custom behavior before `bootstrap` or completely take over the webpack packaging entry, we can place `index.[tj]s` in the `src` or entry directory. There are two cases below:
 
-1. add custom behavior before bootstrap
+## Add custom behavior before bootstrap
 
-Just add default export under `src/index.[tj]s`:
+Just export a function in `src/index.[tj]s`:
 
 ```js title=src/index.js
 import { bootstrap } from '@modern-js/runtime';
@@ -21,9 +21,9 @@ export default App => {
 };
 ```
 
-2. Fully take over the webpack entry
+## Completely take over the webpack entry
 
-When there is no default export function under `src/index.[tj]sx?`, this file is the real webpack entry file, and the code can be organized such as create-react-app:
+When there is no default export function in `src/index.[tj]sx?`, the file is the real webpack packaging entry file and the code can be organized directly as using create-react-app and other scaffolding tools:
 
 ```js title=src/index.jsx
 import React from 'react';