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

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @modern-js/main-doc@2.0.2 build /Users/bytedance/Desktop/workspace/modern-js-main.js/packages/toolkit/main-doc
+> @modern-js/main-doc@2.2.0 build /github/workspace/packages/toolkit/main-doc
 > npx ts-node ./scripts/sync.ts
 

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

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

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

@@ -0,0 +1,39 @@
+---
+sidebar_position: 5
+---
+# build
+
+```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`](/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).

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

@@ -0,0 +1,61 @@
+---
+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/
+```
+
+## Compile Partial Pages
+
+In multi-page (MPA) projects, the `--entry` option can be added to specify one or more pages to compile. In this way, only part of the code in the project will be compiled, and the dev startup speed will be faster.
+
+For example, execute `modern dev --entry`, the entry selector will be displayed in the command line interface:
+
+```bash
+$ modern dev --entry
+
+? Please select the entry that needs to be built
+❯ ◯ foo
+  ◯ bar
+  ◯ baz
+```
+
+For example, if you select the `foo` entry, only the code related to the `foo` entry will be compiled, and the code of other pages will not be compiled.
+
+### Specify the page by parameter
+
+You can also specify the page name through parameters after `--entry`, and the names of multiple pages can be separated by commas.
+
+```bash
+# Compile foo page
+modern dev --entry foo
+
+# Compile foo and bar pages
+modern dev --entry foo,bar
+```

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

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

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

@@ -0,0 +1,61 @@
+---
+sidebar_position: 7
+---
+# inspect
+
+```
+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/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
+```
+
+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.

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

@@ -0,0 +1,54 @@
+---
+sidebar_position: 2
+---
+# new
+
+```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.
+
+### 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/apis/app/commands/serve.mdx

@@ -0,0 +1,27 @@
+---
+sidebar_position: 6
+---
+# serve
+
+```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'](/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,
+  },
+});
+```

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

@@ -0,0 +1,35 @@
+---
+sidebar_position: 3
+---
+# test
+
+```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。
+
+:::

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

@@ -0,0 +1,18 @@
+---
+sidebar_position: 8
+---
+# upgrade
+
+```
+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.

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

@@ -0,0 +1,57 @@
+---
+title: lambda/*.[tj]s
+sidebar_position: 1
+---
+# lambda/*.[tj]s
+
+Declaring API routing in BFF framework mode. Except [some files](/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](/apis/app/hooks/api/functions/api#define-function).

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

@@ -0,0 +1,81 @@
+---
+title: '**/*.[tj]s'
+sidebar_position: 1
+---
+# **/*.[tj]s
+
+Declaring API routing in BFF function mode. Except [some files](/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/apis/app/hooks/api/functions/app.mdx

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

package/en/apis/app/hooks/api/functions/common.mdx

@@ -0,0 +1,9 @@
+---
+title: '**/_*.[tj]s, _*/**'
+sidebar_position: 2
+---
+# **/_*.[tj]s, _*/**
+
+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/apis/app/hooks/api/test.mdx

@@ -0,0 +1,12 @@
+---
+title: test.[tj]s
+sidebar_position: 2
+---
+# test.[tj]s
+
+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/apis/app/hooks/config/html.mdx

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

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

@@ -0,0 +1,16 @@
+---
+title: icon.png
+sidebar_position: 2
+---
+# icon.png
+
+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/apis/app/hooks/config/mock.mdx

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

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

@@ -0,0 +1,30 @@
+---
+title: public/
+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.
+
+## 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/apis/app/hooks/config/storybook.mdx

@@ -0,0 +1,14 @@
+---
+title: storybook/
+sidebar_position: 7
+---
+# storybook/
+
+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/apis/app/hooks/config/upload.mdx

@@ -0,0 +1,44 @@
+---
+title: upload/
+sidebar_position: 4
+---
+# upload/
+
+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](/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/`:
+
+```html
+<script src="/upload/index.js"></script>
+```
+
+if [`output.assetPrefix`](/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.
+
+:::

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

@@ -0,0 +1,9 @@
+---
+title: modern.config.js
+sidebar_position: 8
+---
+# modern.config.js
+
+Modern.js config file, through which you can confiured all aspects of the current project.
+
+For detail, see [configure](/configure/app/usage).