@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-present Modern.js
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# Modern.js Website
+
+### Installation
+
+```
+pnpm i
+```
+
+### Local Development
+
+```
+$ pnpm run dev
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ pnpm run build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.

package/builder-doc/docs/en/config/performance/rsdoctor.md

@@ -0,0 +1,37 @@
+- **Type:** `boolean | { enabled?: boolean; disableClientServer?: boolean; reportDir?: string; mode?: 'normal' | 'brief' | 'lite' }`
+- **Default:** enabled in production build, disabled in development build
+
+Configure [Rsdoctor](https://rsdoctor.dev/) diagnostics for build.
+
+- This config only takes effect when using the Rspack provider.
+- `disableClientServer` defaults to `true` to avoid hanging the build process after report generation.
+- `reportDir` lets you move diagnostics artifacts to a deterministic directory.
+- `mode` controls RsDoctor report mode (`normal`, `brief`, `lite`).
+- Modern.js writes a machine-readable diagnostics contract artifact to:
+  - `<reportDir or outputPath>/.rsdoctor/ultramodern-diagnostics.json`
+  - This contract points coding agents and tools to `.rsdoctor/manifest.json`.
+
+### Example
+
+```js
+export default {
+  performance: {
+    rsdoctor: {
+      enabled: true,
+      disableClientServer: true,
+      reportDir: './artifacts',
+      mode: 'brief',
+    },
+  },
+};
+```
+
+You can also use a boolean:
+
+```js
+export default {
+  performance: {
+    rsdoctor: false,
+  },
+};
+```

package/builder-doc/docs/zh/config/performance/rsdoctor.md

@@ -0,0 +1,37 @@
+- **类型：** `boolean | { enabled?: boolean; disableClientServer?: boolean; reportDir?: string; mode?: 'normal' | 'brief' | 'lite' }`
+- **默认值：** 生产构建默认开启，开发构建默认关闭
+
+用于配置 [Rsdoctor](https://rsdoctor.dev/) 构建诊断。
+
+- 该配置仅在使用 Rspack provider 时生效。
+- `disableClientServer` 默认值为 `true`，用于避免报告生成后构建进程不退出。
+- `reportDir` 可将诊断产物输出到确定的目录。
+- `mode` 用于控制 RsDoctor 报告模式（`normal`、`brief`、`lite`）。
+- Modern.js 会额外生成机器可读诊断契约文件：
+  - `<reportDir 或 outputPath>/.rsdoctor/ultramodern-diagnostics.json`
+  - 该文件可指向 `.rsdoctor/manifest.json`，便于开发者工具与编码代理稳定消费。
+
+### 示例
+
+```js
+export default {
+  performance: {
+    rsdoctor: {
+      enabled: true,
+      disableClientServer: true,
+      reportDir: './artifacts',
+      mode: 'brief',
+    },
+  },
+};
+```
+
+也可以直接使用布尔值：
+
+```js
+export default {
+  performance: {
+    rsdoctor: false,
+  },
+};
+```

package/docs/en/_nav.json

@@ -0,0 +1,36 @@
+[
+  {
+    "text": "guide",
+    "link": "/guides/get-started/introduction",
+    "activeMatch": "/guides/"
+  },
+  {
+    "text": "configure",
+    "link": "/configure/app/usage",
+    "activeMatch": "/configure/"
+  },
+  {
+    "text": "plugin-menu",
+    "link": "/plugin/introduction",
+    "activeMatch": "/plugin/"
+  },
+  {
+    "text": "apis",
+    "link": "/apis/app/commands",
+    "activeMatch": "/apis/"
+  },
+  {
+    "text": "Examples",
+    "link": "/tutorials/foundations/introduction",
+    "activeMatch": "/tutorials/"
+  },
+  {
+    "text": "community",
+    "link": "/community/showcase",
+    "activeMatch": "/community/"
+  },
+  {
+    "text": "Modern.js 2.x Docs",
+    "link": "https://modernjs.dev/v2"
+  }
+]

package/docs/en/apis/_meta.json

@@ -0,0 +1,13 @@
+[
+  "app/commands",
+  {
+    "type": "dir",
+    "name": "app/hooks",
+    "label": "file-conventions"
+  },
+  {
+    "type": "dir",
+    "name": "app/runtime",
+    "label": "runtime-api"
+  }
+]

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

@@ -0,0 +1,215 @@
+---
+sidebar_position: 1
+---
+
+# Commands
+
+Modern.js has some built-in commands that can help you quickly start a development server, build production environment code, and more.
+
+Through this chapter, you can learn about the built-in commands of Modern.js and how to use them.
+
+## modern dev
+
+The `modern dev` command is used to start a local development server and compile the source code in the development environment.
+
+```bash
+Usage: modern dev [options]
+
+Options:
+  -e --entry <entry>    compiler by entry
+  -c --config <config>  specify the configuration file, which can be a relative or absolute path
+  -h, --help            show command help
+  --web-only            only start web service
+  --api-only            only start API service
+```
+
+After running `modern dev`, Modern.js will watch source file changes and apply hot module replacement.
+
+```bash
+$ modern dev
+
+info    Starting dev server...
+
+  > 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:
+
+```text
+$ 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
+```
+
+## modern start
+
+`modern start` is an alias of `modern dev` command, the usage of the two are exactly the same.
+
+## modern build
+
+The `modern build` command will build production-ready artifacts in the `dist/` directory by default. You can specify the output directory by modifying the configuration [`output.distPath`](/configure/app/output/dist-path).
+
+```bash
+Usage: modern build [options]
+
+Options:
+  -c --config <config>  specify the configuration file, which can be a relative or absolute path
+  -h, --help            show command help
+  -w --watch            turn on watch mode, watch for changes and rebuild
+```
+
+## modern new
+
+The `modern new` command is used to enable features in an existing project.
+
+For example, add application entry, enable some optional features such as BFF, micro frontend, etc.
+
+```bash
+Usage: modern new [options]
+
+Options:
+  --config-file <configFile>  specify the configuration file, which can be a relative or absolute path
+  --lang <lang>          set the language (zh or en) for the new command.
+  -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
+```
+
+### Add Entry
+
+In the project, execute the `new` command to add entries as follows:
+
+```text
+$ npx modern new
+? Please select the operation you want: Create Element
+? Please select the type of element to create: New "entry"
+? Please fill in the entry name: entry
+```
+
+### Enable Features
+
+In the project, execute the `new` command to enable features as follows:
+
+```text
+$ npx modern new
+? Please select the operation you want: Enable Features
+? Please select the feature name: (Use arrow keys)
+❯ Enable BFF
+  Enable SSG
+  Enable Micro Frontend
+```
+
+:::tip
+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)】
+:::
+
+import ServeCommand from '@site-docs-en/components/serve-command';
+
+<ServeCommand />
+
+## modern upgrade
+
+Execute the command `npx modern upgrade` in the project, by default, dependencies in the `package.json` are updated to the latest version.
+
+```bash
+Usage: modern upgrade [options]
+
+Options:
+  --config <config> specify the configuration file, which can be a relative or absolute path
+  --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
+```
+
+## modern inspect
+
+The `modern inspect` command is used to view the Modern.js config, [Rsbuild config](https://v2.rsbuild.rs/config/index) and Rspack config of the project.
+
+```bash
+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>  specify the configuration file, which can be a relative or absolute path
+  -h, --help            show command help
+```
+
+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:
+
+- `modern.js.config.mjs`:The Modern.js configuration currently used.
+- `rsbuild.config.mjs`: The Rsbuild config to use at build time.
+- `rspack.config.web.mjs`: The Rspack config used by to use at build time.
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
+
+  - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
+  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
+  - Modern.js Config: /root/my-project/dist/modern.js.config.mjs
+```
+
+### 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 `rspack.config.node.mjs` file will be generated in the `dist/`, corresponding to the Rspack configuration at SSR build time.
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
+
+  - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
+  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
+  - Rspack Config (node): /root/my-project/dist/rspack.config.node.mjs
+  - Modern.js Config: /root/my-project/dist/modern.js.config.mjs
+```
+
+import DeployCommand from '@site-docs-en/components/deploy-command';
+
+<DeployCommand />

package/docs/en/apis/app/hooks/_meta.json

@@ -0,0 +1,28 @@
+[
+  {
+    "type": "dir",
+    "name": "src",
+    "label": "src/",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "api",
+    "label": "api/",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "server",
+    "label": "server/",
+    "collapsed": true
+  },
+  "shared",
+  {
+    "type": "dir",
+    "name": "config",
+    "label": "config/",
+    "collapsed": true
+  },
+  "modern-config"
+]

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

@@ -0,0 +1,13 @@
+---
+title: lambda/*.ts
+sidebar_position: 3
+---
+# lambda/*.ts
+
+After enabling BFF, the files under the `lambda/` directory will be registered as BFF routes according to conventions.
+
+:::note
+The files can be written in `js` or `ts` languages, but they must use `esm` syntax to export functions.
+:::
+
+For detailed information, refer to [BFF API Routes](/guides/advanced-features/bff/function.html#api-routes).

package/docs/en/apis/app/hooks/config/_meta.json

@@ -0,0 +1 @@
+["html", "favicon", "icon", "mock", "public", "upload"]

package/docs/en/apis/app/hooks/config/favicon.mdx

@@ -0,0 +1,29 @@
+---
+title: favicon.*
+sidebar_position: 3
+---
+
+# Favicon
+
+When there is a `favicon.*` file in the `config` directory at the root of the project, Modern.js will automatically set the file to the [html.favicon](/configure/app/html/favicon) configuration option for generating the favicon icon on the page:
+
+```
+./config
+└── favicon.ico
+```
+
+After the build is completed, you can see the following tags automatically generated in HTML:
+
+```html
+<link rel="icon" href="/favicon.ico" />
+```
+
+## Order
+
+When setting up the favicon, Modern.js looks for files in the following order:
+
+- `favicon.png`
+- `favicon.jpg`
+- `favicon.jpeg`
+- `favicon.svg`
+- `favicon.ico`

package/docs/en/apis/app/hooks/config/html.mdx

@@ -0,0 +1,9 @@
+---
+title: html/
+sidebar_position: 1
+---
+# html/
+
+You can inject custom HTML fragments at different locations of the default internal HTML template through the `config/html` directory.
+
+For specific usage, please refer to: [Custom HTML](/guides/basic-features/html).

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

@@ -0,0 +1,29 @@
+---
+title: icon.*
+sidebar_position: 2
+---
+
+# Apple Touch Icon
+
+When there is an `icon.*` file in the `config` directory at the root of the project, Modern.js will automatically set the file to the [html.appIcon](/configure/app/html/app-icon) configuration option for generating the Apple Touch Icon icon under the iOS system.
+
+```
+./config
+└── icon.png
+```
+
+After the build is completed, you can see the following tags automatically generated in HTML:
+
+```html
+<link rel="apple-touch-icon" sizes="180x180" href="/static/image/icon.png" />
+```
+
+## Order
+
+When setting up the app icon, Modern.js looks for files in the following order:
+
+- `icon.png`
+- `icon.jpg`
+- `icon.jpeg`
+- `icon.svg`
+- `icon.ico`

package/docs/en/apis/app/hooks/config/mock.mdx

@@ -0,0 +1,7 @@
+---
+title: mock/
+sidebar_position: 5
+---
+# mock/
+
+When there is a `config/mock/index.js` file in the project directory, Modern.js will automatically enable the Mock service during development.

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

@@ -0,0 +1,30 @@
+---
+title: public/
+sidebar_position: 3
+---
+# public/
+
+Any static assets can be placed in the `public/` directory, and the files will be deployed to the corresponding application domain by the server.
+
+## Description
+
+The file routing is based on the convention of the directory structure, where `public/` is the root directory corresponding to the root path of the Web application.
+
+For example, the `config/public/sdk/index.js` file will be deployed under `${domain}/sdk/index.js` after deployment.
+
+## Scenarios
+
+For example, authentication files required by third-party systems such as `robots.txt` and `auth.xml`.
+
+Or SDKs for other business parties (requiring unchanged routing), or HTML files without entry.
+
+:::info
+For static assets (such as SVG images) that need to be imported through import in the source code, it is recommended to manage them in the `src/assets` directory.
+
+:::
+
+## Code Compression
+
+If the file in the directory is a `.js` file, it will be automatically compressed during production environment construction.
+
+If the file ends with `.min.js`, it will not be compressed.

package/docs/en/apis/app/hooks/config/upload.mdx

@@ -0,0 +1,54 @@
+---
+title: upload/
+sidebar_position: 4
+---
+# upload/
+
+Any static assets can be placed in the `upload/` directory.
+
+## Description
+
+In the development environment, the static assets in this directory will be hosted under the `/upload` path. After building the application, the files in this directory will be copied to the dist directory.
+
+This file convention is mainly used for developers to use plugins to proactively upload static assets to the CDN.
+
+## Scenarios
+
+For example, SDKs for project use only, such as `google-analysis.js` (usually requires HTTP caching).
+
+Pictures, font files, common CSS, etc.
+
+## Code Compression
+
+If the file in the directory is a `.js` file, it will be automatically compressed during production environment construction.
+
+If the file ends with `.min.js`, it will not be compressed.
+
+## More Usage
+
+In React components, you can add this prefix through [Environment Variables](/guides/basic-features/env-vars.html#asset_prefix):
+
+```tsx
+export default () => {
+  return (
+    <img src={`${process.env.ASSET_PREFIX}/upload/banner.png`}></img>
+  );
+};
+```
+
+In addition, whether it is in [Custom HTML](/guides/basic-features/html) or any HTML file under [`config/public/`](/apis/app/hooks/config/public), you can directly use HTML tags to reference resources in the `config/upload/` directory:
+
+```html
+<script src="/upload/index.js"></script>
+```
+
+If you set the [`dev.assetPrefix`](/configure/app/dev/asset-prefix) or [`output.assetPrefix`](/configure/app/output/asset-prefix) prefix, you can also use template syntax to add the prefix directly:
+
+```html
+<script src="<%=assetPrefix %>/upload/index.js"></script>
+```
+
+:::info
+Modern.js does not support using files under `config/upload/` through URLs in `config/public/*.css` (such as background-image).
+
+:::

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

@@ -0,0 +1,9 @@
+---
+title: modern.config.ts
+sidebar_position: 8
+---
+# modern.config.ts
+
+The Modern.js configuration file. Through this file, you can personalize the configuration of various aspects of the current project.
+
+To learn more about how to use the configuration, please refer to [Configuration Usage](/configure/app/usage).

package/docs/en/apis/app/hooks/server/server.mdx

@@ -0,0 +1,10 @@
+---
+title: modern.server.ts
+sidebar_position: 1
+---
+
+# modern.server.ts
+
+This file extends the Modern.js Server. In this file, you can configure [Middleware](/guides/advanced-features/web-server.html#middleware), [RenderMiddleware](/guides/advanced-features/web-server.html#rendermiddleware), or [Plugin](/guides/advanced-features/web-server.html#plugin) for the Server that starts with the Modern.js project.
+
+You can intercept and handle requests and responses, perform authentication and role checks, preprocess requests, and handle exceptions, etc. You can also insert specific business logic into the built-in processing logic (including route matching, resource addressing, header injection, page rendering, and static web hosting).

package/docs/en/apis/app/hooks/shared.mdx

@@ -0,0 +1,7 @@
+---
+title: shared/
+sidebar_position: 5
+---
+# shared/
+
+Shared source code directory. When there is common code in `api/`, `server/`, and `src/` in the project, you can put these codes in the `shared` directory instead of directly referencing them.

package/docs/en/apis/app/hooks/src/app.mdx

@@ -0,0 +1,30 @@
+# App.tsx
+
+The entry identifier when using [Self-controlled Routing](/guides/concept/entries.html#self-controlled-routing) in the application.
+
+`App.tsx` is not the actual application entry; Modern.js will automatically generate the real entry file, which is roughly as follows:
+
+```js
+// runtime-global-context
+import { setGlobalContext } from '@modern-js/runtime/context';
+import App from '@_modern_js_src/App';
+
+setGlobalContext({
+  App,
+});
+
+// index.tsx
+import './runtime-global-context';
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+render(<ModernRoot />, 'root');
+```
+
+When `createRoot` is executed, it will retrieve the registered Global App and generate the actual React component.
+
+:::note
+In scenarios with multiple entry points, each entry can have its own independent `App.tsx`. For more details, see [Entry Points](/guides/concept/entries).
+:::