@modern-js/main-doc 2.1.0 → 2.3.0

package/zh/tutorials/first-app/c08-entries.mdx

@@ -0,0 +1,136 @@
+---
+title: 添加应用入口
+---
+# 添加应用入口
+
+上一个章节中，我们基本完成了联系人列表应用的开发，介绍了 Modern.js 中部分功能的用法，以及推荐的最佳实践。
+
+这一章节中，我们将介绍如何为应用添加新的入口。
+
+## 新建入口
+
+一个完整的项目可能需要多个入口，Modern.js 支持自动创建新入口，前面的章节中提到过，`pnpm run new` 可以启用可选功能。
+
+我们也可以通过它来创建新的工程元素，在项目根目录下执行 `pnpm run new`：
+
+```bash
+? 请选择你想要的操作 创建工程元素
+? 创建工程元素 新建「应用入口」
+? 请填写入口名称 (entry) landing-page
+```
+
+创建完成，项目会变成这样：
+
+```bash
+.
+├── README.md
+├── modern.config.ts
+├── node_modules
+├── package.json
+├── pnpm-lock.yaml
+├── src
+│   ├── modern-app-env.d.ts
+│   ├── landing-page
+│   │   └── routes
+│   │       ├── index.css
+│   │       ├── layout.tsx
+│   │       └── page.tsx
+│   └── myapp
+│       ├── components
+│       │   ├── Avatar
+│       │   │   └── index.tsx
+│       │   └── Item
+│       │       └── index.tsx
+│       ├── containers
+│       │   └── Contacts.tsx
+│       ├── models
+│       │   └── contacts.ts
+│       ├── routes
+│       │   ├── archives
+│       │   │   └── page.tsx
+│       │   ├── layout.tsx
+│       │   └── page.tsx
+│       └── styles
+│           └── utils.css
+└── tsconfig.json
+```
+
+可以看到联系人列表应用的文件，都被自动重构到 `src/myapp/` 里。
+
+同时新建了一个 `src/landing-page/`，里面同样有 `routes/*`（`pnpm run new` 命令只做了这些事，所以你也可以很容易的手动创建新入口或修改入口）
+
+执行 `pnpm run dev`，显示：
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c08-entries-myapp.png)
+
+访问 `http://localhost:8080/`，可以像之前一样看到应用程序。
+
+访问 `http://localhost:8080/landing-page`，可以看到刚创建的新入口 `landing-page` 的页面（Modern.js 自动生成的默认页面）。
+
+Modern.js 框架的设计原则之一是【[约定优于配置（Convention over Configuration）](https://en.wikipedia.org/wiki/Convention_over_configuration)】，多数情况下可以按约定直接写代码，不需要做任何配置，这里 `src/` 中的目录结构就是一种约定：
+
+`src/myapp/` 和 `src/landing-page/` 被自动识别为两个应用入口：myapp 和 landing-page。
+
+其中 `src/myapp/` 的目录名跟项目名（`package.json` 里的 `name`）一致，会被认为是项目**主入口**，项目 URL 的根路径（开发环境里默认是 `http://localhost:8080/`）会自动指向主入口。
+
+其他入口的 URL，是在根路径后追加入口名，比如 `http://localhost:8080/landing-page`。
+
+接下来，我们把 `src/myapp/` 重命名为 `src/contacts/`：
+
+```bash
+mv src/myapp src/contacts
+```
+
+再次执行 `pnpm run dev`，结果变成：
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c08-entries-contacts.png)
+
+现在不再有主入口，联系人列表现在是一个普通入口，需要用 `http://localhost:8080/contacts` 访问。
+
+## 按入口修改配置
+
+我们可以在 Modern.js 配置文件里，自己写代码来控制项目的配置。
+
+现在，修改 `modern.config.ts` 里面添加内容：
+
+```ts
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import tailwindcssPlugin from '@modern-js/plugin-tailwindcss';
+
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+    ssrByEntries: {
+      'landing-page': false,
+    },
+  },
+  plugins: [appTools(), tailwindcssPlugin()],
+});
+```
+
+执行 `pnpm run dev`，再用浏览器打开 `view-source:http://localhost:8080/landing-page`，可以看到 `landing-page` 网页内容是通过 js 动态加载的，且此页面的 SSR 功能被关闭。
+
+如果注释掉 `ssrByEntries` 和它的值，landing-page 的 SSR 功能就恢复开启了。
+
+还有一些时候，需要一些更复杂的逻辑来做设置，比如需要 JS 变量、表达式、导入模块等，例如在只在开发环境里开启 SSR：
+
+```js
+export default defineConfig({
+  server: {
+    ssrByEntries: {
+      'landing-page': process.env.NODE_ENV !== 'production',
+    },
+  },
+};
+```
+
+到底为止，我们的联系人列表应用的雏形就基本完成了 👏👏👏。
+
+## 下一步
+
+接下来你可以通过了解[指南](/guides/get-started/quick-start)、[配置](/configure/app/usage) 等更多教程，进一步完善你的应用。

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/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,30 +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,10 +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,8 +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).