@modern-js/main-doc 2.1.0 → 2.2.0

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

@@ -0,0 +1,136 @@
+---
+title: Add Application Entry
+---
+# Add Application Entry
+
+In the last chapter, we basically completed the development of the point of contact list application, introduced the usage of some functions in the Modern.js, and recommended best practices.
+
+In this chapter, we will describe how to add a new entry to the application.
+
+## New entry
+
+A complete project may require multiple entries, Modern.js supports the automatic creation of new entries, as mentioned in the previous section, `pnpm run new` can enable optional features.
+
+We can also use it to create new project elements and execute `pnpm run new` in the project root directory:
+
+```bash
+? Action Create project element
+? Create project element New "entry"
+? Entry name (entry) landing-page
+```
+
+When created, the project will look like this:
+
+```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
+```
+
+You can see that the files of the contact list application are automatically refactored into `src/myapp/`.
+
+At the same time, a new `src/landing-page/` is created, which also has `routes/*` (the `pnpm run new` command only does these things, so you can also easily create new entries or modify entries manually).
+
+Execute `pnpm run dev` to display:
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c08-entries-myapp.png)
+
+Access `http://localhost:8080/` to see the application as before.
+
+Visit `http://localhost:8080/landing-page` to see the landing-page for the new entry you just created (Modern.js automatically generated default page).
+
+One of the design principles of the Modern.js framework is [[Convention over Configuration](https://en.wikipedia.org/wiki/Convention_over_configuration) ]. In most cases, you can write code directly by convention without any configuration. The directory structure in `src/` is a convention:
+
+`src/myapp/` and `src/landing-page/` are automatically identified as two application portals: myapp and landing-page.
+
+The directory name of `src/myapp/` is the same as the project name (`name` in `package.json`), which will be considered as the main entry of the project, and the root path of the project URL (the default in the development environment is `http://localhost:8080/`) will automatically point to the main entry.
+
+The URL of other entries is to append the entry name after the root path, such as `http://localhost:8080/landing-page`.
+
+Next, we rename `src/myapp/` to `src/contacts/`:
+
+```bash
+mv src/myapp src/contacts
+```
+
+Execute `pnpm run dev` again, the result becomes:
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c08-entries-contacts.png)
+
+There is no longer a main entry, the point of contact list is now a normal entry that needs to be accessed with `http://localhost:8080/contacts`.
+
+## Modify the configuration by entry
+
+In the Modern.js configuration file, we can write our own code to control the configuration of the project.
+
+Now, modify the `modern.config.ts` to add something:
+
+```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()],
+});
+```
+
+Execute `pnpm run dev`, and then open `view-source: http://localhost:8080/landing-page` with the browser, you can see that the content of the `landing-page` web page is dynamically loaded through js, and the SSR function of this page is turned off.
+
+If `ssrByEntries` and its value are annotated, the SSR function of landing-page is restored.
+
+Other times, you need some more sophisticated logic to do the setup, such as JS variables, expressions, import modules, etc., for example, only in the development environment to enable SSR:
+
+```js
+export default defineConfig({
+  server: {
+    ssrByEntries: {
+      'landing-page': process.env.NODE_ENV !== 'production',
+    },
+  },
+};
+```
+
+So far, the prototype of our point of contact list application is almost complete 👏👏👏.
+
+## Next step
+
+Then you can further refine your application by following more tutorials like [Guides](/guides/get-started/quick-start), [configuration](/configure/app/usage), and more.

package/en/tutorials/foundations/introduction.mdx

@@ -0,0 +1,47 @@
+---
+title: Introduce
+sidebar_position: 1
+---
+# Introduce
+
+Welcome to Modern.js tutorials!
+
+After reading this section, you will have an initial understanding of Modern.js and use Modern.js to create your first application.
+
+:::note Follow
+Join our Lark group to ask questions and learn about the latest news.
+
+:::
+
+## What is Modern.js
+
+**Modern.js** is a progressive modern web development framework based on React.
+
+The framework has a variety of built-in out-of-the-box tools, excellent build performance, zero-configuration rendering paradigm switching, and integrated API calls. Starting from three solutions (Application solutions, Module solutions, Monorepo solutions), it supports front-end research and development of a complete period.
+
+Modern.js is ByteDance's underlying front-end framework, which has directly or indirectly served thousands of applications, including middle and back-end, PC Web, H5 and other application scenarios. The framework covers a full life cycle, has a complete plugin system, and provides a high degree of customization capabilities. Support custom solutions exclusive to business lines through generator plugin, customize various functional extensions and business requirements, and help developers build applications faster.
+
+## Why Modern.js
+
+Modern.js can provide developers with the ultimate **Development Experience**，make the app better **User Experience**。
+
+In the process of developing React applications, developers often need to design implementations for certain functions, or use other libraries and frameworks to solve these problems。
+
+Modern.js support all the configuration and tools required by React applications, and have built-in **additional functions and optimizations**. Developers can use React to build the UI of the application, and then gradually adopt Modern.js functions to solve common application requirements, such as routing, data fetch, state management, etc.
+
+It mainly contains the following features:
+
+- 🪜 **Progressive**：Create projects with the most streamlined templates, gradually turn on plugin capabilities through generators, and customize solutions.
+- 🏠 **Integration**：The development is unique to the production environment Web Server, CSR and SSR are isomorphic development, and the function as the API service call.
+- 📦 **Out Of The Box**：Default TS support, built-in build core, ESLint, debugging tools, full functionality can be tested.
+- 🌏 **Ecology**：Self-developed state management, micro frontend, module packaging, Monorepo solution and other peripheral requirements.
+- 🕸 **Routing Modes**：Contains controlled routing, routing based on file conventions (nested routing), configurable routing, etc。
+- 🚀 **Independently Build Core**：Support a variety of packaging tools, deep optimization bundle.
+
+## Next
+
+{/* If you are a front-end beginner, you may find these concepts a bit complicated. We provide some [JavaScript and React](/tutorials/foundations/basic) learning materials, you can do some understanding of them first。
+
+If you are an experienced developer and want to know how to use Modern.js, you can try [Create your first app](/tutorials/first-app/c01-start), or read [Guide](/guides/get-started/quick-start).  */}
+
+If you want to know how to use Modern.js, you can try [Create your first app](/tutorials/first-app/c01-start), or read [Guide](/guides/get-started/quick-start).

package/package.json

@@ -11,20 +11,21 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.1.0",
+  "version": "2.2.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.1.0"
+    "@modern-js/builder-doc": "^2.2.0"
   },
   "devDependencies": {
     "ts-node": "^10",
+    "typescript": "^4",
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.1.0"
+    "@modern-js/builder-doc": "2.2.0"
   },
   "scripts": {
     "build": "npx ts-node ./scripts/sync.ts"

package/scripts/config.ts

@@ -43,15 +43,8 @@ const hyphenate = function (str: string) {
 const configPath = 'configure/app';
 const getBaseDir = (lng: Language) => {
   const cwd = process.cwd();
-  const baseDir =
-    lng === 'zh'
-      ? path.join(cwd, lng, configPath)
-      : path.join(
-          cwd,
-          lng,
-          'docusaurus-plugin-content-docs/current',
-          configPath,
-        );
+  const baseDir = path.join(cwd, lng, configPath);
+
   return baseDir;
 };
 
@@ -61,7 +54,7 @@ export const gen = (jsonMap: Record<Language, Summary[]>) => {
     const json = jsonMap[lng as Language];
     json.forEach(summary => {
       const mdDir = path.join(baseDir, summary.dirname);
-      const mdPath = path.join(mdDir, `${hyphenate(summary.name)}.md`);
+      const mdPath = path.join(mdDir, `${hyphenate(summary.name)}.mdx`);
       if (!fs.existsSync(mdDir)) {
         fs.mkdirpSync(mdDir);
       }

package/zh/apis/app/commands/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "命令",
-  "position": 3,
+  "position": 0,
   "link": {
     "type": "doc",
     "id": "apis/app/commands/index"

package/zh/apis/app/commands/build.mdx

@@ -0,0 +1,39 @@
+---
+sidebar_position: 5
+---
+# build
+
+```bash
+Usage: modern build [options]
+
+build application
+
+Options:
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help  显示命令帮助
+  --analyze   分析构建产物体积，查看各个模块打包后的大小
+```
+
+`modern build` 命令默认会在 `dist/` 目录下构建出可用于生产环境的产物。
+
+可以通过修改配置 [`output.distPath`](/configure/app/output/dist-path) 指定产物的输出目录。
+
+## 分析构建产物体积
+
+执行 `npx modern build --analyze` 命令，可以在打包生产环境代码的同时，产出一个分析构建产物体积的 HTML 文件：
+
+```
+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
+```
+
+手动在浏览器中打开上述 HTML 文件，可以看到打包产物的瓦片图，并进行包体积分析和优化：
+
+<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png" />
+
+> 该功能基于 [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) 实现。

package/zh/apis/app/commands/dev.mdx

@@ -0,0 +1,61 @@
+---
+sidebar_position: 1
+---
+
+# dev / start
+
+```bash
+Usage: modern dev / modern start [options]
+
+本地开发命令
+
+Options:
+  -e --entry <entry>    指定入口，只编译特定的页面
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help            显示命令帮助
+  --analyze             分析构建产物体积，查看各个模块打包后的大小
+  --api-only            仅启动 API 接口服务
+```
+
+`modern dev` 命令用于启动一个本地开发服务器，对源代码进行开发环境编译，同时监听源文件变化，默认支持模块热更新和 React Fast Refresh。
+
+`modern start` 是 `modern dev` 命令的别名，两者的功能和用法完全一致。
+
+```bash
+$ modern dev
+
+info    Starting dev server...
+info    App running at:
+
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+## 编译部分页面
+
+在多页面（MPA）项目中，可以添加 `--entry` 参数来指定编译其中的一个或多个页面。这样可以只编译项目中的部分代码，从而提升 dev 启动速度。
+
+比如执行 `modern dev --entry`，在命令行界面中会展示入口选择框：
+
+```bash
+$ modern dev --entry
+
+? 请选择需要构建的入口
+❯ ◯ foo
+  ◯ bar
+  ◯ baz
+```
+
+比如选择 `foo` 入口，那么只有 `foo` 入口相关的代码会进行编译，其他页面的代码将不会参与构建。
+
+### 通过参数指定页面
+
+你也可以在 `--entry` 后面通过参数来指定页面名称，多个页面的名称使用逗号分隔。
+
+```bash
+# 编译 foo 页面
+modern dev --entry foo
+
+# 编译 foo 和 bar 页面
+modern dev --entry foo,bar
+```

package/zh/apis/app/commands/inspect.mdx

@@ -0,0 +1,61 @@
+---
+sidebar_position: 7
+---
+# inspect
+
+```
+Usage: modern inspect [options]
+
+Options:
+  --env <env>           查看指定环境下的配置 (default: "development")
+  --output <output>     指定在 dist 目录下输出的路径 (default: "/")
+  --verbose             在结果中展示函数的完整内容
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help            显示命令帮助
+```
+
+`modern inspect` 命令，用于查看项目的 [Modern.js Builder 配置](https://modernjs.dev/builder/guide/basic/builder-config.html) 以及 webpack 配置。
+
+在项目根目录下执行命令 `npx modern inspect` 后，会在项目的 `dist` 目录生成以下文件：
+
+- `builder.config.js`: 表示在构建时使用的 Modern.js Builder 配置。
+- `webpack.config.web.js`: 表示在构建时使用的 webpack 配置。
+
+```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
+```
+
+## 指定环境
+
+默认情况下，inspect 命令会输出开发环境的配置，你可以添加 `--env production` 选项来输出生产环境的配置：
+
+```bash
+modern inspect --env production
+```
+
+## 完整内容
+
+默认情况下，inspect 命令会省略配置对象中的函数内容，你可以添加 `--verbose` 选项来输出函数的完整内容：
+
+```bash
+modern inspect --verbose
+```
+
+## SSR 构建配置
+
+如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `webpack.config.node.js` 文件，对应 SSR 构建时的 webpack 配置。
+
+```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/zh/apis/app/commands/lint.mdx

@@ -0,0 +1,19 @@
+---
+sidebar_position: 4
+title: lint
+---
+# 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
+```
+
+运行 `ESLint` 检查代码语法情况。通常情况下，我们只需要在 `git commit` 阶段通过 `lint-staged` 检查本次提交修改的部分代码。
+
+- `--no-fix` 参数设置后可以关闭自动修复 lint 错误代码的能力。

package/zh/apis/app/commands/new.mdx

@@ -0,0 +1,54 @@
+---
+sidebar_position: 2
+---
+# new
+
+```bash
+Usage: modern new [options]
+
+应用工程中执行生成器
+
+Options:
+  -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
+  -c, --config <config>  生成器运行默认配置(JSON 字符串)
+  --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
+  --registry             生成器运行过程中定制 npm Registry
+  -h, --help             显示命令帮助
+```
+
+`modern new` 命令用于在已有项目中添加项目元素。
+
+比如添加应用入口、启用启用一些可选功能如 Tailwind CSS、微前端开发模式等。
+
+### 添加入口
+
+在应用工程中，执行 `new` 命令添加入口如下：
+
+```bash
+$ npx modern new
+? 请选择你想要的操作 创建工程元素
+? 创建工程元素 新建「应用入口」
+? 请填写入口名称 entry
+```
+
+### 启用可选功能
+
+在应用工程中，执行 `new` 命令启用可选能力如下：
+
+```bash
+$ npx modern new
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 (Use arrow keys)
+❯ 启用 Tailwind CSS 支持
+  启用「BFF」功能
+  启用「微前端」模式
+  启用「单元测试 / 集成测试」功能
+  启用「Visual Testing (Storybook)」模式
+```
+
+:::caution 注意
+`--config` 参数对应参数值需要使用 JSON 字符串。
+
+pnpm 暂不支持使用 JSON 字符串作为参数值，可使用 `npm new` 开启相关功能。【[相关 Issue](https://github.com/pnpm/pnpm/issues/3876)】
+
+:::

package/zh/apis/app/commands/serve.mdx

@@ -0,0 +1,27 @@
+---
+sidebar_position: 6
+---
+# serve
+
+```bash
+Usage: modern serve [options]
+
+run server
+
+Options:
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help            显示命令帮助
+  --api-only            仅启动 API 接口服务
+```
+
+通常使用 `modern serve` 命令在生产环境下启用应用工程, 需要提前执行 [`build`](/apis/app/commands/build) 命令构建出对应产物。
+
+默认情况下，应用将会在 `localhost:8080` 启动，可以通过 `server.port` 修改 Server 端口号：
+
+```js
+export default defineConfig({
+  server: {
+    port: 8081,
+  },
+});
+```

package/zh/apis/app/commands/test.mdx

@@ -0,0 +1,35 @@
+---
+sidebar_position: 3
+---
+# test
+
+```bash
+Usage: modern test [options]
+
+Options:
+  -h, --help  显示命令帮助
+```
+
+:::caution 注意
+`modern test` 命令需要先通过 [`new`](/apis/app/commands/new) 命令启用「单元测试 / 集成测试」功能
+
+:::
+
+`modern test` 命令会自动运行项目下的测试用例，效果如下：
+
+```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 注
+`src` 和 `api` 目录下面 `*.test.(js|ts)` 都会默认识别为测试用例。
+
+:::

package/zh/apis/app/commands/upgrade.mdx

@@ -0,0 +1,18 @@
+---
+sidebar_position: 8
+---
+# upgrade
+
+```
+Usage: modern upgrade [options]
+
+升级 Modern.js 到最新版本
+
+Options:
+  --registry <registry>  定制 npm registry (default: "")
+  -d,--debug             开启 Debug 模式，打印调试日志信息 (default: false)
+  --cwd <cwd>            项目路径 (default: "")
+  -h, --help             display help for command
+```
+
+在项目根目录下执行命令 `npx modern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 Modern.js 相关依赖更新至最新版本。

package/zh/apis/app/hooks/api/framework/lambda.mdx

@@ -0,0 +1,57 @@
+---
+title: lambda/*.[tj]s
+sidebar_position: 1
+---
+# lambda/*.[tj]s
+
+在 BFF 框架写法下，声明 API 路由的文件。除了[某些约定文件](/apis/app/hooks/api/framework/lambda#白名单)外，`api/` 目录下的文件会被注册为接口的路由。
+
+:::info
+使用 `api` 目录需要开启 BFF 功能，需要在项目下执行 new 命令启用「BFF」功能。
+
+:::
+
+:::tip
+该文件支持使用 `js` 或 `ts` 语言，但必须使用 `esm` 语法导出函数。
+
+:::
+
+## 路由规则
+
+### 默认路由
+
+路由系统会将以 `index` 命名的文件会被映射到上一层目录。
+
+- `api/lambda/index.ts` -> `$BASENAME/`
+- `api/lambda/user/index.ts` -> `$BASENAME/user`
+
+### 多级路由
+
+路由系统也支持解析多级的文件，如果创建文件夹结构，文件仍会以相同方式自动解析路由。
+
+- `api/lambda/hello.ts` -> `$BASENAME/hello`
+- `api/lambda/user/list.ts` -> `$BASENAME/user/list`
+
+### 动态路由
+
+同样的，你可以通过创建带有 `[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`
+
+其中的 `$BASENAME` 可以在 `modern.config.js` 中进行配置，默认值为 `/api`。
+
+### 白名单
+
+默认 `api` 目录下所有文件都会当作 BFF 函数文件去解析，但同样我们也设置了白名单，这些文件不被被解析：
+
+- 命名以 `_` 开头的文件。例如：`_utils.ts`。
+- 命名以 `_` 开头的文件夹下所有文件。例如：`_utils/index.ts`、`_utils/cp.ts`。
+- 测试文件。例如：`foo.test.ts`。
+- TypeScript 类型文件。例如：`hello.d.ts`。
+- `node_module` 下的文件。
+
+## 函数定义
+
+和函数写法下[函数定义](/apis/app/hooks/api/functions/api#define-function)完全一致。