@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

package/zh/tutorials/foundations/introduction.mdx

@@ -0,0 +1,45 @@
+---
+title: 介绍
+sidebar_position: 1
+---
+# 介绍
+
+欢迎来到 Modern.js 教程！
+
+阅读本栏目后，你将初步理解 Modern.js，并使用 Modern.js 创建第一个应用。
+
+:::note 关注
+加入我们的飞书群，咨询相关问题，了解最新动态。
+
+:::
+
+## Modern.js 是什么
+
+**Modern.js** 是基于 React 的渐进式现代 Web 开发框架。
+
+框架内置多种开箱即用的开发工具，拥有极致的构建性能，支持零配置的渲染范式切换，一体化的 API 调用。并从三种工程方案出发（应用工程方案、模块工程方案，Monorepo 工程方案），支持全链路的前端研发。
+
+Modern.js 是字节跳动的底层前端研发框架，已经直接或间接的服务上千个应用，包括中后台、PC Web、H5 等多种应用场景。框架覆盖完整的生命周期，拥有完善的插件体系，提供高度定制能力。支持通过生成器插件自定义业务线专属的工程方案，定制各种功能扩展和业务需求，帮助开发者更快速的搭建应用。
+
+## 为什么使用 Modern.js
+
+Modern.js 能为开发者提供极致的**开发体验（Development Experience）**，让应用拥有更好的**用户体验（User Experience）**。
+
+在开发 React 应用过程中，开发者通常需要去为某些功能去设计实现方案，或是使用其他的库、框架来解决这些问题。Modern.js 支持 React 应用所需要的所有配置和工具，并内置**额外的功能和优化**。开发者可以使用 React 构建应用的 UI，然后逐步采用 Modern.js 的功能来解决常见的应用需求，如路由、数据获取、状态管理等。
+
+它主要包含以下特点：
+
+- 🪜 **渐进式**：使用最精简的模板创建项目，通过生成器逐步开启插件功能，定制解决方案。
+- 🏠 **一体化**：开发与生产环境 Web Server 唯一，CSR 和 SSR 同构开发，函数即接口的 API 服务调用。
+- 📦 **开箱即用**：默认 TS 支持，内置构建、ESLint、调试工具，全功能可测试。
+- 🌏 **周边生态**：自研状态管理、微前端、模块打包、Monorepo 方案等周边需求。
+- 🕸 **多种路由模式**：包含自控路由、基于文件约定的路由（嵌套路由）等。
+- 🚀 **独立构建核心**：支持多种打包工具，深度优化构建产物。
+
+## 下一步
+
+{/* 如果你是前端初学者，可能会觉得这些概念有些复杂。我们提供了一些 [JavaScript 和 React](/tutorials/foundations/basic) 的学习资料，你可以先对它们做些了解。
+
+如果你是有经验的开发者，希望了解如何使用 Modern.js，你可以尝试[创建第一个应用](/tutorials/first-app/c01-start)，或是阅读[指南](/guides/get-started/quick-start)。  */}
+
+如果你希望了解如何使用 Modern.js，可以尝试[创建第一个应用](/tutorials/first-app/c01-start)，或是阅读[指南](/guides/get-started/quick-start)。

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/_category_.json

@@ -1,8 +0,0 @@
-{
-  "label": "Commands",
-  "position": 3,
-  "link": {
-    "type": "doc",
-    "id": "apis/app/commands/index"
-  }
-}

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/build.md

@@ -1,44 +0,0 @@
----
-sidebar_position: 5
----
-
-```bash
-Usage: modern build [options]
-
-build application
-
-Options:
-  -c --config <config>  configuration file path, which can be a relative path or an absolute path
-  -h, --help            show command help
-  --analyze             analyze the bundle and view size of each module
-```
-
-`modern build` command will by default build production in `dist/`.
-
-you can configure the [`output.distPath`](/docs/configure/app/output/dist-path) specifies the output directory for the product.
-
-## Analyze Bundle
-
-execute `npx modern build --analyze` command，can produce an HTML file that analyzes the volume of the bundle while packaging the production code:
-
-```
-Bundle Analyzer saved report to /example/dist/report.html
-File sizes after production build:
-
-  122.35 KB  dist/static/js/885.1d4fbe5a.js
-  2.3 KB     dist/static/js/main.4b8e8d64.js
-  761 B      dist/static/js/runtime-main.edb7cf35.js
-  645 B      dist/static/css/main.0dd3ecc1.css
-```
-
-Open the above HTML file in the browser, you can see the tile diagram of the packaged product, and perform package volume analysis and optimization:
-
-<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png" />
-
-> this features based on [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer).
-
-## Command Arguments
-
-import CommandTip from '@site-docs-en/components/command-tip.md'
-
-<CommandTip />

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/dev.md

@@ -1,36 +0,0 @@
----
-sidebar_position: 1
----
-
-# dev / start
-
-```bash
-Usage: modern dev / modern start [options]
-
-Development commands
-
-Options:
-  -e --entry <entry>    compiler by entry
-  -c --config <config>  configuration file path, which can be a relative path or an absolute path
-  -h, --help            show command help
-  --analyze             analyze the bundle and view size of each module
-  --api-only            only start API service
-```
-
-`modern dev` start a development server，watch file change，default support React Fast Refresh:
-
-`modern start` is an alias of `modern dev` command, the usage of the two are exactly the same.
-
-```bash
-$ modern dev
-
-info    Starting dev server...
-info    App running at:
-
-  > Local:    http://localhost:8080/
-  > Network:  http://192.168.0.1:8080/
-```
-
-import CommandTip from '@site-docs-en/components/command-tip.md'
-
-<CommandTip />

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/index.md

@@ -1,12 +0,0 @@
----
-type: ref
----
-
-# Commands
-
-This section covers all commands.
-
-
-
-
-

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/inspect.md

@@ -1,60 +0,0 @@
----
-sidebar_position: 7
----
-
-```
-Usage: modern inspect [options]
-
-Options:
-  --env <env>           view the configuration in the target environment (default: "development")
-  --output <output>     Specify the path to output in the dist (default: "/")
-  --verbose             Show the full function in the result
-  -c --config <config>  configuration file path, which can be a relative path or an absolute path
-  -h, --help            show command help
-```
-
-`modern inspect` command used to view the [Modern.js Builder config](https://modernjs.dev/builder/en/guide/basic/builder-config.html) and webpack config of the project.
-
-After executing the command `npx modern inspect` in the project root directory, the following files will be generated in the `dist` directory of the project:
-
-- `builder.config.js`: The Modern.js Builder config to use at build time.
-- `webpack.config.web.js`: The webpack config used by to use at build time.
-
-```bash
-➜ npx modern inspect
-
-Inspect config succeed, open following files to view the content:
-
-  - Builder Config: /root/my-project/dist/builder.config.js
-  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
-```
-
-## Configuration Env
-
-By default, the inspect command will output the development configs, you can use the `--env production` option to output the production configs:
-
-```bash
-modern inspect --env production
-```
-
-## Verbose content
-
-By default, the inspect command will omit the function content in the config object, you can use the `--verbose` option to output the full content of the function:
-
-```bash
-modern inspect --verbose
-```
-
-### SSR Configuration
-
-If the project has enabled SSR, an additional `webpack.config.node.js` file will be generated in the `dist/`, corresponding to the webpack configuration at SSR build time.
-
-```bash
-➜ npx modern inspect
-
-Inspect config succeed, open following files to view the content:
-
-  - Builder Config: /root/my-project/dist/builder.config.js
-  - Webpack Config (web): /root/my-project/dist/webpack.config.web.js
-  - Webpack Config (node): /root/my-project/dist/webpack.config.node.js
-```

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/lint.md

@@ -1,22 +0,0 @@
----
-sidebar_position: 4
-title: lint
----
-
-```bash
-Usage: modern lint [options] [...files]
-
-lint and fix source files
-
-Options:
-  --no-fix    disable auto fix source file
-  -h, --help  display help for command
-```
-
-Run ESLint to check the syntax of the code. Normally, only the part of the code modified by this commit needs to be checked by `lint-staged` during the `git commit` phase.
-
-* `--no-fix` close auto fix by lint.
-
-import CommandTip from '@site-docs-en/components/command-tip.md'
-
-<CommandTip />

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/new.md

@@ -1,56 +0,0 @@
----
-sidebar_position: 2
----
-
-```bash
-Usage: modern new [options]
-
-Execution Generator in App
-
-Options:
-  -d, --debug            using debug mode to log something (default: false)
-  -c, --config <config>  set default generator config(json string)
-  --dist-tag <tag>       use specified tag version for its generator
-  --registry             set npm registry url to run npm command
-  -h, --help             show command help
-```
-
-The `modern new` command is used to enable features to an existing project.
-
-For example, add application entry, enable some optional features such as Tailwind CSS, micro frontend, etc.
-
-import CommandTip from '@site-docs-en/components/command-tip.md'
-
-<CommandTip />
-
-### Add Entry
-
-In the project, execute the `new` command to add entries as follows:
-
-```bash
-$ npx modern new
-? 请选择你想要的操作 创建工程元素
-? 创建工程元素 新建「应用入口」
-? 请填写入口名称 entry
-```
-
-### Enable Features
-
-In the project, execute the `new` command to enable features as follows:
-
-```bash
-$ npx modern new
-? 请选择你想要的操作 启用可选功能
-? 启用可选功能 (Use arrow keys)
-❯ 启用 Tailwind CSS 支持
-  启用「BFF」功能
-  启用「微前端」模式
-  启用「单元测试 / 集成测试」功能
-  启用「Visual Testing (Storybook)」模式
-```
-
-:::caution
-The `--config` parameter needs to use a JSON string.
-
-pnpm does not support the use of JSON strings as parameter values currently. Use `npm new` to turn on.【[Relate Issue](https://github.com/pnpm/pnpm/issues/3876)】
-:::

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/serve.md

@@ -1,32 +0,0 @@
----
-sidebar_position: 6
----
-
-```bash
-Usage: modern serve [options]
-
-run server
-
-Options:
-  -c --config <config>  configuration file path, which can be a relative path or an absolute path
-  -h, --help            show command help
-  --api-only            only run API service
-```
-
-Usually use the `modern serve` command to enable project run in the production environment, and you need to execute the [`build'](/docs/apis/app/commands/build) command in advance to build the product.
-
-By default, the project will run in `localhost:8080`, you can modify the Server port number with `server.port`:
-
-```js
-export default defineConfig({
-  server: {
-    port: 8081,
-  }
-})
-```
-
-import CommandTip from '@site-docs-en/components/command-tip.md'
-
-<CommandTip />
-
-

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/test.md

@@ -1,36 +0,0 @@
----
-sidebar_position: 3
----
-
-```bash
-Usage: modern test [options]
-
-Options:
-  -h, --help  show command help
-```
-
-:::caution
-`modern test` command need to execute the `new` command in advance to enable the `unit test/integration test`.
-:::
-
-`modern test` command will automatically run the test cases, the effect is as follows:
-
-```bash
-$ npx modern test
- PASS  src/tests/index.test.ts
-  The add method
-    ✓ should work fine. (2ms)
-
-Test Suites: 1 passed, 1 total
-Tests:       1 passed, 1 total
-Snapshots:   0 total
-Time:        0.994 s, estimated 1 s
-```
-
-:::info
-files match `*.test.(js|ts)` in `api/` or `src/` will be recognized as test cases by default。
-:::
-
-import CommandTip from '@site-docs-en/components/command-tip.md'
-
-<CommandTip />

package/en/docusaurus-plugin-content-docs/current/apis/app/commands/upgrade.md

@@ -1,21 +0,0 @@
----
-sidebar_position: 8
----
-
-```
-Usage: modern upgrade [options]
-
-upgrade Modern.js to latest version.
-
-Options:
-  --registry <registry>  specify npm registry (default: "")
-  -d,--debug             using debug mode to log something (default: false)
-  --cwd <cwd>            app directory (default: "")
-  -h, --help             show command help
-```
-
-Execute the command `npx modern upgrade` in the project, by default, dependencies in the `package.json` are updated to the latest version.
-
-:::info
-the command is available in `@modern-js/app-tools` version >= 1.17.0, previous versions can be upgraded with `npx @modern-js/upgrade`.
-:::

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/api/framework/lambda.md

@@ -1,54 +0,0 @@
----
-title: lambda/*.[tj]s
-sidebar_position: 1
----
-
-Declaring API routing in BFF framework mode. Except [some files](/docs/apis/app/hooks/api/framework/lambda#allow-list)，files in `api/` are registered as routes.
-
-:::info
-use `api/` need execute new command to enable the 「BFF」 feature.
-:::
-
-:::tip
-this file supports the use `js` or `ts`, but the functions must be exported using the ESM syntax.
-:::
-
-## Routing Rule
-
-### Default Route
-
-The files named `index` will be upper level routing:
-
-* `api/lambda/index.ts` -> `$BASENAME/`
-* `api/lambda/user/index.ts` -> `$BASENAME/user`
-
-### Multi Level Route
-
-The routing system also supports parsing multiple levels of files. and if you create a folder, the files will still be automatically parsed in the same way.
-
-* `api/lambda/hello.ts` -> `$BASENAME/hello`
-* `api/lambda/user/list.ts` -> `$BASENAME/user/list`
-
-### Dynamic Route
-
-Dynamic named routing parameters can be supported by creating folders or files with `[xxx]`.
-
-* `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`，the default value is `/api`。
-
-### Allow List
-
-By default, all files in the `api/` will be parsed as BFF function. but we also set a allow list, and these files will not be parsed:
-
-* file name start with `_`, for example: `_utils.ts`.
-* files in directory that name start with `_`, for example：`_utils/index.ts`、`_utils/cp.ts`.
-* test files, for example：`foo.test.ts`.
-* TypeScript define files, for example：`hello.d.ts`.
-* files in `node_module`.
-
-## Define Function
-
-the same as [Define Function](/docs/apis/app/hooks/api/functions/api#define-function).

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/api/functions/api.md

@@ -1,78 +0,0 @@
----
-title: "**/*.[tj]s"
-sidebar_position: 1
----
-
-Declaring API routing in BFF function mode. Except [some files](/docs/apis/app/hooks/api/functions/api#allow-list)，files in `api/` are registered as routes.
-
-:::info
-use `api/` need execute new command to enable the 「BFF」 feature.
-:::
-
-:::tip
-this file supports the use `js` or `ts`, but the functions must be exported using the ESM syntax.
-:::
-
-## Routing Rule
-
-### Default Route
-
-The files named `index` will be upper level routing:
-
-* `api/index.ts` -> `$BASENAME/`
-* `api/user/index.ts` -> `$BASENAME/user`
-
-### Multi Level Route
-
-The routing system also supports parsing multiple levels of files. and if you create a folder, the files will still be automatically parsed in the same way.
-
-* `api/hello.ts` -> `$BASENAME/hello`
-* `api/user/list.ts` -> `$BASENAME/user/list`
-
-### Dynamic Route
-
-Dynamic named routing parameters can be supported by creating folders or files with `[xxx]`.
-
-* `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`，the default value is `/api`。
-
-### Allow List
-
-By default, all files in the `api/` will be parsed as BFF function. but we also set a allow list, and these files will not be parsed:
-
-* file name start with `_`, for example: `_utils.ts`.
-* files in directory that name start with `_`, for example：`_utils/index.ts`、`_utils/cp.ts`.
-* test files, for example：`foo.test.ts`.
-* TypeScript define files, for example：`hello.d.ts`.
-* files in `node_module`.
-
-## Define Function
-
-In addition to the above routing rules, the function definition and export in the code also have conventions.
-
-function need named exports，and the name of the exported function is the HTTP Method:
-
-```ts
-export const get = async () => {
-  return {
-    name: 'Modern.js',
-    desc: 'Modern web Solutions',
-  };
-};
-```
-
-Export the function like above will generate a `POST` interface.
-
-App support 9 Method definitions: `GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`. so App can use these name as function export nane.
-
-The name is insensitive, whaterver `get`、`Get`、`GEt`、`GET`, can be accurately identified. And default export, `export default xxx` will be `Get` method.
-
-because `delete` is a keyword in JavaScript, use `del` or `DELETE` instead.
-
-Multiple functions of different Methods can be defined in one file, but if multiple functions of the same Method are defined, only the first can work.
-
-:::info
-It should be noted that the defined functions should be asynchronous, which is related to the type when the function is called.

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/api/functions/app.md

@@ -1,12 +0,0 @@
----
-title: _app.[tj]s
-sidebar_position: 3
----
-
-in BFF function mode，this file can add middleware before [BFF 函数](/docs/apis/app/hooks/api/functions/api).
-
-:::note
-For detail, see [hook](/docs/apis/app/runtime/bff/hook)
-:::
-
-

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/api/functions/common.md

@@ -1,10 +0,0 @@
----
-title: "**/_*.[tj]s, _*/**"
-sidebar_position: 2
----
-
-under BFF function mode, these files are not registered as routes.
-
-Any files that not routes, but required in the project can be named in this way.
-
-

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/api/test.md

@@ -1,10 +0,0 @@
----
-title: test.[tj]s
-sidebar_position: 2
----
-
-App's BFF test file，support for writing test cases in the `api/` directory which file with suffix `.test.[tj]s`.
-
-:::info
-To use unit test and integration test, you need to execute the `new` command in advance to enable the `unit test/integration test`.
-:::

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/config/html.md

@@ -1,8 +0,0 @@
----
-title: html/
-sidebar_position: 1
----
-
-The `config/html` directory allows you to inject custom html snippets in different places in the default html template.
-
-For detail, see [HTML](/docs/guides/basic-features/html).

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/config/icon.md

@@ -1,15 +0,0 @@
----
-title: icon.png
-sidebar_position: 2
----
-
-When `config/icon.png` exist, it can inject app icon information into the html page at build time:
-
-```
-.config
-└── icon.png
-```
-
-the app icon `link` meta will be injected into the html, as follows:
-
-![app-icon](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/api/app-icon.png)

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/config/mock.md

@@ -1,6 +0,0 @@
----
-title: mock/
-sidebar_position: 5
----
-
-when `config/mock/index.js` exist，Modernjs auto start the Mock service in the development.

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/config/public.md

@@ -1,28 +0,0 @@
----
-title: public/
-sidebar_position: 3
----
-
-Static resource files in any format can be placed in the `public/`, and the files will be Served under the web application domain name.
-
-## 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.
-
-For example, the `config/public/sdk/index.js` file will be Served under `${domain}/sdk/index.js` after deployment.
-
-## Scene
-
-For example, `robots.txt`, `auth.xml` and other authentication file.
-
-SDK (requiring the same routing) for other business, or an HTML file for static host.
-
-:::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.
-:::
-
-## Compression
-
-If the file is a `.js` file, it will be automatically compressed when the production environment is built.
-
-If the file ends with `.min.js`, it will not compression.

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/config/storybook.md

@@ -1,12 +0,0 @@
----
-title: storybook/
-sidebar_position: 7
----
-
-Modern.js.js supports debugging with Storybook. When you need to configure Storybook, configure it in the `config/storybook/`.
-
-For detail, see [Storybook](https://storybook.js.org/docs/react/configure/overview).
-
-:::info
-Debugging with Storybook requires executing the `new` command to enable the 「Visual Testing (Storybook)」 mode feature.
-:::

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/config/upload.md

@@ -1,42 +0,0 @@
----
-title: upload/
-sidebar_position: 4
----
-
-Static resource files in any format can be placed in the `upload/`.
-
-## 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.
-
-This file convention is mainly used for developers to use plugins to upload static resource files to the CDN.
-
-## Scene
-
-For example, the SDK used by the project such as `google-analysis.js` (usually requires http caching).
-
-Images, font files, generic CSS, etc.
-
-## Compression
-
-If the file is a `.js` file, it will be automatically compressed when the production environment is built.
-
-If the file ends with `.min.js`, it will not compression.
-
-## More Usage
-
-Whether in [custom HTML](/docs/guides/basic-features/html), or in any HTML file under ['config/public/'](/docs/apis/app/hooks/config/public), you can directly use the HTML tag to refer to the resources in the `config/upload/`:
-
-```html
-<script src="/upload/index.js"></script>
-```
-
-if [`output.assetPrefix`](/docs/configure/app/output/asset-prefix) is configured，add this prefix directly using template syntax:
-
-```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.
-:::