@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.98 → 3.8.1-ultramodern.1

package/docs/apis/app/commands.md

@@ -0,0 +1,231 @@
+# Commands
+
+UltraModern.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 UltraModern.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`, UltraModern.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.md).
+
+```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 runtime status
+
+The `modern runtime status` command reads the runtime status endpoint and prints the response. It targets `http://127.0.0.1:8080/_modern/runtime/status` by default.
+
+```bash
+Usage: modern runtime status [options]
+
+Options:
+  --endpoint <endpoint>  runtime status endpoint URL or path
+  --token <token>        runtime status auth token
+  --token-env <name>     environment variable name that stores runtime status auth token (default: "MODERN_RUNTIME_SIGNAL_TOKEN")
+  --header-name <name>   auth header name (default: "x-modernjs-runtime-signal-token")
+  --timeout <ms>         request timeout in milliseconds (default: "5000")
+  --json                 output as JSON format for machine reading
+  -h, --help             display help for command
+```
+
+If `--endpoint` is a path, it is resolved against `http://127.0.0.1:8080`. If `--token` is omitted, the command reads the token from the environment variable named by `--token-env`.
+
+By default, the command formats the response as readable key/value lines. Add `--json` to print the raw JSON payload.
+
+```bash
+modern runtime status --json
+```
+
+## modern runtime fallback-signal
+
+The `modern runtime fallback-signal` command posts a runtime fallback signal to the canary contract-gate endpoint. It targets `http://127.0.0.1:8080/_modern/contract-gates/runtime-fallback` by default.
+
+```bash
+Usage: modern runtime fallback-signal [options]
+
+Options:
+  --app <appName>          remote app name
+  --endpoint <endpoint>    runtime fallback signal endpoint URL or path
+  --reason <reason>        fallback reason (default: "runtime_fallback")
+  --phase <phase>          fallback phase (default: "load")
+  --entry <entry>          remote entry URL
+  --runtime-digest <digest>  runtime digest value
+  --metadata <json>        metadata JSON object string
+  --token <token>          runtime signal auth token
+  --token-env <name>       environment variable name that stores runtime signal auth token (default: "MODERN_RUNTIME_SIGNAL_TOKEN")
+  --header-name <name>     auth header name (default: "x-modernjs-runtime-signal-token")
+  --timeout <ms>           request timeout in milliseconds (default: "5000")
+  --json                   output as JSON format for machine reading
+  -h, --help               display help for command
+```
+
+The request body always includes `appName`, `reason`, and `phase`. It includes `entry`, `runtimeDigest`, and `metadata` only when those options are provided. `--metadata` must be a JSON object string.
+
+```bash
+modern runtime fallback-signal --app crm-shell --reason remote_load_failed --phase load --json
+```
+
+## modern serve
+
+The `modern serve` command is used to start an UltraModern.js project in the production environment. It can also be used to preview the artifacts built for the production environment locally. Please note that you need to execute the [`build`](/apis/app/commands.md#modern-build) command beforehand to generate the corresponding artifacts.
+
+```bash
+Usage: modern serve [options]
+
+Options:
+  -c --config <config>  specify the configuration file, which can be a relative or absolute path
+  -h, --help            show command help
+  --api-only            only run API service
+```
+
+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,
+  },
+});
+```
+
+## modern inspect
+
+The `modern inspect` command is used to view the UltraModern.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
+```
+
+## modern deploy
+
+The `modern deploy` command is used to generate artifacts required for the deployment platform.
+
+```bash
+Usage: modern deploy [options]
+
+Options:
+  -c --config <config>  Specify configuration file path, either relative or absolute
+  -s --skip-build       Skip the build stage
+  -h, --help            Display command help
+```
+
+For more details, refer to [Deploy Application](/guides/basic-features/deploy.md).

package/docs/apis/app/hooks/api/lambda.md

@@ -0,0 +1,9 @@
+# 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.md#api-routes).

package/docs/apis/app/hooks/config/favicon.md

@@ -0,0 +1,24 @@
+# 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.md) 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/apis/app/hooks/config/html.md

@@ -0,0 +1,5 @@
+# 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.md).

package/docs/apis/app/hooks/config/icon.md

@@ -0,0 +1,24 @@
+# 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.md) 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/apis/app/hooks/config/mock.md

@@ -0,0 +1,6 @@
+# mock/
+
+When there is a `config/mock/index.ts` or `config/mock/index.js` file in the
+project directory, Modern.js will automatically enable the Mock service during
+development. Use [`dev.mockDir`](/configure/app/dev/mock-dir.md) to customize
+this directory.

package/docs/apis/app/hooks/config/public.md

@@ -0,0 +1,26 @@
+# 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/apis/app/hooks/config/upload.md

@@ -0,0 +1,50 @@
+# 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.md#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.md) or any HTML file under [`config/public/`](/apis/app/hooks/config/public.md), 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.md) or [`output.assetPrefix`](/configure/app/output/asset-prefix.md) 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/apis/app/hooks/modern-config.md

@@ -0,0 +1,5 @@
+# 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.md).

package/docs/apis/app/hooks/server/server.md

@@ -0,0 +1,5 @@
+# modern.server.ts
+
+This file extends the Modern.js Server. In this file, you can configure [Middleware](/guides/advanced-features/web-server.md#middleware), [RenderMiddleware](/guides/advanced-features/web-server.md#rendermiddleware), or [Plugin](/guides/advanced-features/web-server.md#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/apis/app/hooks/shared.md

@@ -0,0 +1,3 @@
+# 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/apis/app/hooks/src/app.md

@@ -0,0 +1,30 @@
+# App.tsx
+
+The entry identifier when using [Self-controlled Routing](/guides/concept/entries.md#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.md).
+:::

package/docs/apis/app/hooks/src/entry.md

@@ -0,0 +1,34 @@
+# entry.tsx
+
+Normally, the [`routes/`](/apis/app/hooks/src/routes.md) and [`App.tsx`](/apis/app/hooks/src/app.md) hook files can meet our needs. When we need to add custom behavior before component rendering or take full control of the Rspack packaging entry, we can create `entry.ts` file in the src or entry directory. Here are two cases for discussion。
+
+## Add custom behavior before Render
+
+This is implemented in `src/entry.ts` as follows:
+
+```js title=src/entry.tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+async function beforeRender() {
+  // todo
+}
+
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```
+
+## Take full control of the Rspack entry
+
+When the project does not install the `@modern-js/runtime` dependency, `src/entry.tsx?` is the real Rspack packaging entry file, and you can directly organize the code like using create-react-app and other scaffolds:
+
+```js title=src/entry.jsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+```

package/docs/apis/app/hooks/src/entry.server.md

@@ -0,0 +1,51 @@
+# entry.server.tsx
+
+When the project initiates `server.ssr`, Modern.js generates a default Server-Side entry. The sample code is as follows:
+
+```tsx title="entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+  type HandleRequest,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
+  const body = await renderString(request, <ServerRoot />, options);
+
+  return new Response(body, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## Add Custom Entry Points
+
+Users need to customize the Server-Side Rendering entry points, they can customize the server entry in `src/entry.server.ts` or `src/{entryName}/entry.server.ts`.
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+  type HandleRequest,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
+  // do something before rendering
+  const body = await renderString(request, <ServerRoot />, options);
+
+  const newBody = body + '<div>Byte-Dance</div>';
+
+  return new Response(newBody, {
+    headers: {
+      'content-type': 'text/html; charset=UTF-8',
+      'x-custom-header': 'abc',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```

package/docs/apis/app/hooks/src/modern.runtime.md

@@ -0,0 +1,5 @@
+# modern.runtime.ts
+
+The Modern.js Runtime configuration file allows for personalized configuration of the Runtime capabilities for the current project.
+
+For specific usage of the configuration, please refer to [Runtime Configuration](/configure/app/runtime/0-intro.md).

package/docs/apis/app/hooks/src/routes.md

@@ -0,0 +1,86 @@
+# routes/
+
+The identifier for the entry point when the application uses [Conventional Routing](/guides/basic-features/routes/routes.md#conventional-routing).
+
+Conventional routing uses `routes/` as the convention for the entry point and analyzes the files in the `src/routes` directory to obtain the client-side routing configuration.
+
+Any `layout.tsx` and `page.tsx` under `src/routes` will be used as the application's routes:
+
+```bash
+.
+└── routes
+    ├── layout.tsx  # [!code highlight]
+    ├── page.tsx # [!code highlight]
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+## Basic Example
+
+The directory name under `routes` will be used as the mapping of the route URL. `layout.tsx` is used as the layout component and `page.tsx` is used as the content component in the routing. They are the leaf nodes of the entire route. For example, the following directory structure:
+
+```bash
+.
+└── routes
+    ├── page.tsx
+    └── user
+        └── page.tsx
+```
+
+will generate two routes:
+
+- `/`
+- `/user`
+
+## Dynamic Routing
+
+If the directory name of the route file is named with `[]`, the generated route will be used as a dynamic route. For example, the following file directory:
+
+```
+└── routes
+    ├── [id]
+    │   └── page.tsx
+    ├── blog
+    │   └── page.tsx
+    └── page.tsx
+```
+
+The `routes/[id]/page.tsx` file will be converted to the `/:id` route. Except for the `/blog` route that can be matched exactly, all other `/xxx` routes will be matched to this route.
+
+In the component, you can use [useParams](/apis/app/runtime/router/router.md#useparams) to obtain the corresponding named parameter.
+
+When using the [loader](/guides/basic-features/data/data-fetch.md#the-loader-function) function to obtain data, `params` will be passed as an input parameter to the `loader` function, and the corresponding parameter can be obtained through the attribute of `params`.
+
+## Layout Component
+
+In the following example, a common layout component can be added to all route components by adding `layout.tsx`:
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+In the layout component, you can use `<Outlet>` to represent the child components:
+
+```tsx title=routes/layout.tsx
+import { Link, Outlet, useLoaderData } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <>
+      <Outlet></Outlet>
+    </>
+  );
+};
+```
+
+:::note
+`<Outlet>` is an API provided by React Router. For details, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+
+:::

package/docs/apis/app/hooks/src/server.md

@@ -0,0 +1,3 @@
+# \*.\[server|node].tsx
+
+Used in the application project to place server-side code. When `*.tsx` and `*.[server|node].tsx` coexist, SSR will prefer to use the `*.[server|node].tsx` file instead of the `*.tsx` file when rendering on the server.

package/docs/apis/app/runtime/bff/use-backend-context.md

@@ -0,0 +1,27 @@
+# useHonoContext
+
+Used to obtain backend request context in an integrated BFF function.
+
+## Usage
+
+```ts
+import { useHonoContext } from '@modern-js/server-runtime';
+```
+
+## Function Signature
+
+`function useHonoContext(): Context`
+
+## Example
+
+Developers can use `context` to obtain more request information, such as setting response headers:
+
+```ts
+import { useHonoContext } from '@modern-js/server-runtime';
+
+export async function get() {
+  const c = useHonoContext();
+  c.res.headers.set('x-bff-api', 'true');
+  // ...
+}
+```

package/docs/apis/app/runtime/core/create-root.md

@@ -0,0 +1,19 @@
+# createRoot
+
+It is used to create the root component provided by Modern.js, which will automatically register Runtime plugins and complete the initialization of Runtime plugins.
+
+## Usage
+
+```ts
+import { createRoot } from '@modern-js/runtime/react';
+```
+
+## Function Signature
+
+```ts
+export function createRoot(UserApp?: React.ComponentType | null): React.ComponentType<any>;
+```
+
+### Parameters
+
+- `UserApp`: an optional parameter, and the default is the component exported from `App.tsx`.