@modern-js/main-doc 2.0.0-beta.0 → 2.0.0-beta.1

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @modern-js/main-doc@2.0.0-beta.1 build /github/workspace/packages/toolkit/main-doc
+> npx ts-node ./scripts/sync.ts
+

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

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

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

@@ -0,0 +1,44 @@
+---
+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/components/command-tip.md'
+
+<CommandTip />

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

@@ -0,0 +1,31 @@
+---
+sidebar_position: 1
+---
+
+# dev
+
+```bash
+Usage: modern dev [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:
+
+```bash
+App running at:
+
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+import CommandTip from '@site-docs/components/command-tip.md'
+
+<CommandTip />

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

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

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

@@ -0,0 +1,39 @@
+---
+sidebar_position: 7
+---
+
+```
+Usage: modern inspect [options]
+
+inspect internal webpack config
+
+Options:
+  --env <env>           view the configuration in the target environment (default: "development")
+  --output <output>     Specify the path to output in the dist (default: "/")
+  --no-console          Do not output the full result in shell
+  --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 full webpack configuration of the project.
+
+Executing the command `npx modern inspect` in the project will output the webpack configuration on the shell, and will also generate a `webpack.client.inspect.js` file in the project's `dist` directory, which developers can open and view manually.
+
+## Configuration Env
+
+By default, the webpack configuration of the development environment is output. And the `env` option can be used to output the configuration of the production environment:
+
+```bash
+modern inspect --env production
+```
+
+## Configuration Type
+
+### SSR Configuration
+
+If the project has SSR enable, an additional `webpack.ssr.inspect.js` file will be generated in the `dist/`, corresponding to the webpack configuration at SSR build time.
+
+### Modern Configuration
+
+if project enable [enableModernMode](/docs/configure/app/output/enable-modern-mode), an additional `webpack.modern.inspect.js` file will be generated in the `dist/`corresponding to the webpack configuration at modern web build.

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

@@ -0,0 +1,22 @@
+---
+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/components/command-tip.md'
+
+<CommandTip />

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

@@ -0,0 +1,59 @@
+---
+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/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 支持
+  启用 Less 支持
+  启用 Sass 支持
+  启用「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/start.md

@@ -0,0 +1,32 @@
+---
+sidebar_position: 6
+---
+
+```bash
+Usage: modern start [options]
+
+start 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 start API service
+```
+
+Usually use the `modern start` command to enable project start 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 start 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/components/command-tip.md'
+
+<CommandTip />
+
+

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

@@ -0,0 +1,36 @@
+---
+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/components/command-tip.md'
+
+<CommandTip />

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

@@ -0,0 +1,21 @@
+---
+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/_category_.json

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

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

@@ -0,0 +1,4 @@
+{
+  "label": "api/",
+  "position": 2
+}

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/api/framework/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "框架写法",
+  "position": 2
+}

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

@@ -0,0 +1,54 @@
+---
+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/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "函数写法",
+  "position": 1
+}

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

@@ -0,0 +1,78 @@
+---
+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

@@ -0,0 +1,12 @@
+---
+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

@@ -0,0 +1,10 @@
+---
+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

@@ -0,0 +1,10 @@
+---
+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/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "config/",
+  "position": 6
+}

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

@@ -0,0 +1,8 @@
+---
+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

@@ -0,0 +1,15 @@
+---
+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

@@ -0,0 +1,6 @@
+---
+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

@@ -0,0 +1,28 @@
+---
+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

@@ -0,0 +1,12 @@
+---
+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

@@ -0,0 +1,42 @@
+---
+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.
+:::

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

@@ -0,0 +1,7 @@
+---
+type: ref
+---
+
+# Convention
+
+This section covers all documentation conventions.

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

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

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

@@ -0,0 +1,4 @@
+{
+  "label": "server/",
+  "position": 3
+}