@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.99 → 3.8.1-ultramodern.2

package/docs/guides/advanced-features/bff/{operators.mdx → operators.md}

@@ -1,8 +1,3 @@
----
-sidebar_position: 2
-title: Creating Extensible BFF Functions
----
-
 # Creating Extensible BFF Functions
 
 The previous section showed how to export a simple BFF function in a file. In more complex scenarios, each BFF function may need to do independent type validation, pre-logic, etc.
@@ -31,10 +26,6 @@ A BFF function created by the `Api` function consists of the following parts:
 
 The server can define the input parameters and types of the interface. Based on the types, the server will automatically perform type validation at runtime:
 
-import BFFOperatorCode from '@site-docs/components/bff-operator-code';
-
-<BFFOperatorCode>
-
 ```typescript title="api/lambda/user.ts"
 import { Api, Post, Query, Data } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -59,8 +50,6 @@ export const addUser = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 :::caution Note
 When using the `Api` function, ensure that all code logic is placed inside the function. Operations such as `console.log` or using `fs` outside the function are not allowed.
 
@@ -86,8 +75,6 @@ addUser({
 
 As shown in the example below, you can specify the route and HTTP Method through the `Get` function:
 
-<BFFOperatorCode>
-
 ```typescript title="api/lambda/user.ts"
 import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
 
@@ -100,12 +87,8 @@ export const getHello = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 When the route is not specified, the interface route is defined according to the file convention. As shown in the example below, with the function writing method, there is a code path `api/lambda/user.ts`, which will register the corresponding interface `/api/user`.
 
-<BFFOperatorCode>
-
 ```typescript title="api/lambda/user.ts"
 import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
 
@@ -113,10 +96,8 @@ import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
 export const get = Api(Query(UserSchema), async ({ query }) => query);
 ```
 
-</BFFOperatorCode>
-
 :::info
-Modern.js recommends defining interfaces based on file conventions to keep routes clear in the project. For specific rules, see [Function Routes](/guides/advanced-features/bff/function#function-routes).
+Modern.js recommends defining interfaces based on file conventions to keep routes clear in the project. For specific rules, see [Function Routes](/guides/advanced-features/bff/function.md#function-routes).
 
 :::
 
@@ -140,8 +121,6 @@ The following are request-related operators. Operators can be combined, but must
 
 Using the `Query` function, you can define the type of query. After using the `Query` function, the query information can be obtained in the input parameters of the interface processing function, and the `query` field can be added to the input parameters of the frontend request function:
 
-<BFFOperatorCode>
-
 ```typescript title="api/lambda/user.ts"
 // Server-side code
 import { Api, Query } from '@modern-js/plugin-bff/hono-server';
@@ -157,8 +136,6 @@ export const get = Api(Query(UserSchema), async ({ query }) => ({
 }));
 ```
 
-</BFFOperatorCode>
-
 ```typescript title="routes/page.tsx"
 // Frontend code
 get({
@@ -173,8 +150,6 @@ get({
 
 URL query parameters are strings by default. If you need numeric types, you need to use `z.coerce.number()` for type conversion:
 
-<BFFOperatorCode>
-
 ```typescript title="api/lambda/user.ts"
 import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -198,8 +173,6 @@ export const getUser = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 :::caution Note
 URL query parameters are all string types. If you need numeric types, you need to use `z.coerce.number()` for conversion, not `z.number()` directly.
 :::
@@ -213,8 +186,6 @@ If you use the Data function, you must follow the HTTP protocol. When the HTTP M
 
 :::
 
-<BFFOperatorCode>
-
 ```typescript title="api/lambda/user.ts"
 import { Api, Data } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -230,8 +201,6 @@ export const post = Api(Data(DataSchema), async ({ data }) => ({
 }));
 ```
 
-</BFFOperatorCode>
-
 ```typescript title="routes/page.tsx"
 // Frontend code
 post({
@@ -246,8 +215,6 @@ post({
 
 Route parameters can implement dynamic routes and get parameters from the path. You can specify path parameters through `Params<T>(schema: z.ZodType<T>)`
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Get, Params } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -265,14 +232,10 @@ export const queryUser = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ### Request Headers
 
 You can define the request headers required by the interface through the `Headers<T>(schema: z.ZodType<T>)` function and pass the request headers through integrated calls:
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Headers } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -286,8 +249,6 @@ export const queryUser = Api(Headers(headerSchema), async ({ headers }) => ({
 }));
 ```
 
-</BFFOperatorCode>
-
 ## Parameter Validation
 
 As mentioned earlier, when using functions such as `Query` and `Data` to define interfaces, the server will automatically validate the data passed from the frontend based on the schema passed to these functions.
@@ -333,8 +294,6 @@ The `Middleware` operator can be configured multiple times, and the execution or
 
 :::
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Query, Middleware } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -356,8 +315,6 @@ export const get = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ## Data Transformation Pipe
 
 The `Pipe` operator can pass in a function that executes after middleware and validation are completed. It can be used in the following scenarios:
@@ -373,8 +330,6 @@ The `Pipe` operator can be configured multiple times. The execution order of fun
 
 :::
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -401,12 +356,8 @@ export const get = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 Also,
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -436,12 +387,8 @@ export const get = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 If you need to do more custom operations on the response, you can pass a function to the `end` function. The input parameter of the function is Hono's Context (`c`), and you can operate on `c.req` and `c.res`:
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -474,8 +421,6 @@ export const get = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ## Response
 
 The following are response-related operators. Through response operators, you can process responses.
@@ -484,8 +429,6 @@ The following are response-related operators. Through response operators, you ca
 
 You can specify the status code returned by the interface through the `HttpCode(statusCode: number)` function
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Query, Data, HttpCode } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -514,14 +457,10 @@ export const post = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ### Response Headers SetHeaders
 
 Supports setting response headers through the `SetHeaders(headers: Record<string, string>)` function
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Get, SetHeaders } from '@modern-js/plugin-bff/hono-server';
 
@@ -534,14 +473,10 @@ export default Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ### Redirect
 
 Supports redirecting the interface through `Redirect(url: string)`:
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Get, Redirect } from '@modern-js/plugin-bff/hono-server';
 
@@ -552,13 +487,9 @@ export default Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ## Request Context
 
-As mentioned above, through operators, you can get `query`, `data`, `params`, etc. in the input parameters of the interface processing function. But sometimes we need to get more request context information. At this time, we can get it through [`useHonoContext`](/apis/app/runtime/bff/use-backend-context):
-
-<BFFOperatorCode>
+As mentioned above, through operators, you can get `query`, `data`, `params`, etc. in the input parameters of the interface processing function. But sometimes we need to get more request context information. At this time, we can get it through [`useHonoContext`](/apis/app/runtime/bff/use-backend-context.md):
 
 ```typescript title="api/lambda/user.ts"
 import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
@@ -584,8 +515,6 @@ export const queryUser = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ## FAQ
 
 ### Can I use TypeScript instead of zod schema
@@ -607,8 +536,6 @@ For specific comparisons of different solutions, you can refer to [Why Use Zod](
 
 In frontend development, some server interfaces (such as some configuration interfaces) have long response times, but actually don't need to be updated for a long time. For such interfaces, we can set HTTP cache to improve page performance:
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, SetHeaders } from '@modern-js/plugin-bff/hono-server';
 
@@ -625,5 +552,3 @@ export const get = Api(
   },
 );
 ```
-
-</BFFOperatorCode>

package/docs/{components/bff-upload.mdx → guides/advanced-features/bff/upload.md}

@@ -1,3 +1,7 @@
+# File Upload
+
+BFF combined with runtime framework provides file upload capabilities, supporting integrated calls and pure function manual calls.
+
 ### BFF Function
 
 First, create the `api/lambda/upload.ts` file:

package/docs/guides/advanced-features/{bff.mdx → bff.md}

@@ -1,7 +1,3 @@
----
-title: BFF
----
-
 # BFF
 
 BFF (Backends for Frontends) is an architectural pattern primarily used to address issues of data aggregation in front-end and back-end collaboration. Under the BFF architecture, front-end applications do not communicate directly with backend services. Instead, they interact with backend services through a dedicated BFF middleware layer, custom-made for the front end.

package/docs/guides/advanced-features/{build-performance.mdx → build-performance.md}

@@ -1,7 +1,3 @@
----
-sidebar_position: 12
----
-
 # Improve Build Performance
 
 Modern.js optimizes build performance by default, but as the project becomes larger, you may encounter some build performance problems.
@@ -9,7 +5,7 @@ Modern.js optimizes build performance by default, but as the project becomes lar
 This document provides some optional speed-up strategies, developers can choose some of them to improve the build performance.
 
 :::tip 📢 Notice
-The strategies in [Bundle Size Optimization](/guides/advanced-features/page-performance/optimize-bundle) can also be used to improve build performance, so we won't repeat them here.
+The strategies in [Bundle Size Optimization](/guides/advanced-features/page-performance/optimize-bundle.md) can also be used to improve build performance, so we won't repeat them here.
 :::
 
 ## General optimization strategy
@@ -96,7 +92,7 @@ export default {
 
 ### Adjust Browserslist for development
 
-This strategy is similar to ["Adjust Browserslist"](/guides/advanced-features/page-performance/optimize-bundle#adjust-browserslist), the difference is that we can set different browserslist for development and production environment, thereby reducing the compilation overhead in the development environment.
+This strategy is similar to ["Adjust Browserslist"](/guides/advanced-features/page-performance/optimize-bundle.md#adjust-browserslist), the difference is that we can set different browserslist for development and production environment, thereby reducing the compilation overhead in the development environment.
 
 For example, you can add the following config to `package.json`, which means that only the latest browsers are compatible in the development environment, and the actual browsers are compatible in the production environment:
 
@@ -131,4 +127,4 @@ export default {
 };
 ```
 
-See [output.sourceMap](/en/configure/app/output/source-map.html) for details.
+See [output.sourceMap](/configure/app/output/source-map.md) for details.

package/docs/guides/advanced-features/{compatibility.mdx → compatibility.md}

@@ -1,7 +1,3 @@
----
-sidebar_position: 6
----
-
 # Browser Compatibility
 
 ## Browserslist Configuration
@@ -14,10 +10,12 @@ Modern.js supports setting the range of browsers that a web application needs to
 
 When you create a new Modern.js project, a default `.browserslistrc` configuration is included, which indicates that JavaScript code will be compiled to ES6 format.
 
-import DefaultBrowserslist from '@site-docs/components/default-browserslist';
-
-<DefaultBrowserslist />
-
+```yaml title=".browserslistrc"
+chrome >= 87
+edge >= 88
+firefox >= 78
+safari >= 14
+```
 
 When the `overrideBrowserslist` configuration is not specified in the project, this `.browserslistrc` file will take effect.
 
@@ -36,7 +34,7 @@ You can also configure browserslist by setting the `browserslist` field in the `
 
 ### Method 3: Configure via `output.overrideBrowserslist`
 
-You can also configure browserslist by setting the [`output.overrideBrowserslist`](/configure/app/output/override-browserslist) field in the `modern.config.js` file:
+You can also configure browserslist by setting the [`output.overrideBrowserslist`](/configure/app/output/override-browserslist.md) field in the `modern.config.js` file:
 
 ```js title="modern.config.js"
 export default {
@@ -59,9 +57,6 @@ In most scenarios, it is recommended to prioritize using the `.browserslistrc` f
 Please refer to [Rsbuild - Setting Browser Range](https://v2.rsbuild.rs/zh/guide/advanced/browserslist) for more information.
 :::
 
-import UpgradeBrowserslist from '@site-docs-en/components/upgrade-browserslist';
-
-<UpgradeBrowserslist />
 
 ## Polyfill
 
@@ -72,10 +67,54 @@ Modern.js by default injects corresponding polyfill code at compile time through
 By default, it will include the necessary polyfill code based on the project's Browserslist settings, so you generally do not need to worry about polyfill issues for your project source code and third-party dependencies. However, since some unused polyfill code is included, the final bundle size may increase.
 
 :::info
-For scenarios where certain third-party dependencies clearly do not require polyfills, you can set [`output.polyfill`](/configure/app/output/polyfill) to `usage`. This way, Babel will only inject polyfill code based on the syntax used in the code during compilation.
+For scenarios where certain third-party dependencies clearly do not require polyfills, you can set [`output.polyfill`](/configure/app/output/polyfill.md) to `usage`. This way, Babel will only inject polyfill code based on the syntax used in the code during compilation.
 
 :::
 
-import UAPolyfill from '@site-docs/components/ua-polyfill';
+### 运行时按需 Polyfill
+
+Modern.js 中还提供了基于浏览器 [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) 信息的运行时按需 Polyfill 方案，相比于 Babel 优势如下：
+
+- 不会插入到代码中，只根据访问页面的设备，按需下发 Polyfill 代码 ，减少整体代码体积。
+- 相同浏览器会公用一份 Polyfill 代码。因此，随着项目越来越多，基于 UA 的 Polyfill 代码下发速度会越来越快，综合速度超过常规方案。
+
+Modern.js 提供了 `@modern-js/plugin-polyfill` 插件来实现该功能，可以通过安装该插件来开启该功能：
+
+
+```sh [npm]
+npm install @modern-js/plugin-polyfill
+```
+
+```sh [yarn]
+yarn add @modern-js/plugin-polyfill
+```
+
+```sh [pnpm]
+pnpm add @modern-js/plugin-polyfill
+```
+
+然后在 `modern.config.ts` 中注册 Polyfill 插件:
+
+```ts title="modern.config.ts"
+import { polyfillPlugin } from '@modern-js/plugin-polyfill';
+
+export default defineConfig({
+  plugins: [..., polyfillPlugin()],
+});
+```
+
+配置 `output.polyfill` 为 `ua` 并且执行 `pnpm run build && pnpm run serve` 启动服务器后，访问页面可以看到 HTML 产物中包含如下脚本:
 
-<UAPolyfill />
+```js
+<script src="/__polyfill__" crossorigin></script>
+```
+
+在 Chrome 51 下访问页面可以看到 `http://localhost:8080/__polyfill__` 返回内容如下:
+
+![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
+
+:::caution 注意
+该功能只有在使用 Modern.js 内置的 Web Server 时才会生效。
+
+如果有自定义模版的需求，请参考 [HTML 模板](/zh/guides/basic-features/html.md)。通过 `html.template` 或 `tools.html` 手动修改模版时，可能会导致该功能无法正确生效。
+:::

package/docs/guides/advanced-features/international/{advanced.mdx → advanced.md}

@@ -1,7 +1,3 @@
----
-title: Advanced Usage
----
-
 # Advanced Usage
 
 ## SSR Scenarios

package/docs/guides/advanced-features/international/{api.mdx → api.md}

@@ -1,7 +1,3 @@
----
-title: API Reference
----
-
 # API Reference
 
 ## useModernI18n
@@ -10,15 +6,15 @@ title: API Reference
 
 ### Return Value
 
-| Field | Type | Description |
-| --- | --- | --- |
-| `language` | `string` | Current language code |
-| `changeLanguage` | `(lang: string) => Promise<void>` | Switches language |
-| `supportedLanguages` | `string[]` | Supported language list, from `localeDetection.languages` |
-| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | Localised URL mapping from `localeDetection.localisedUrls` |
-| `isLanguageSupported` | `(lang: string) => boolean` | Checks whether a language is in the supported list |
-| `isResourcesReady` | `boolean` | Whether translation resources for the current language have finished loading |
-| `i18nInstance` | `I18nInstance` | i18next instance for advanced scenarios |
+| Field                 | Type                                                | Description                                                                  |
+| --------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `language`            | `string`                                            | Current language code                                                        |
+| `changeLanguage`      | `(lang: string) => Promise<void>`                   | Switches language                                                            |
+| `supportedLanguages`  | `string[]`                                          | Supported language list, from `localeDetection.languages`                    |
+| `localisedUrls`       | `boolean \| Record<string, Record<string, string>>` | Localised URL mapping from `localeDetection.localisedUrls`                   |
+| `isLanguageSupported` | `(lang: string) => boolean`                         | Checks whether a language is in the supported list                           |
+| `isResourcesReady`    | `boolean`                                           | Whether translation resources for the current language have finished loading |
+| `i18nInstance`        | `I18nInstance`                                      | i18next instance for advanced scenarios                                      |
 
 When `localePathRedirect` is enabled and `localisedUrls` is omitted, Modern.js keeps prefix-only paths such as `/en/about`. Translated path segments are enabled only by a non-empty `localisedUrls` map. Route generation validates every localisable path and every configured language only while that map is enabled.
 
@@ -88,13 +84,13 @@ A route link component with a locale prefix.
 
 ### Props
 
-| Prop | Type | Required | Description |
-| --- | --- | --- | --- |
-| `to` | `string` | Yes | Target path. Do not include the locale prefix |
-| `children` | `React.ReactNode` | Yes | Link content |
-| `replace` | `boolean` | No | Uses `history.replace` instead of `push` |
-| `state` | `any` | No | State passed to the target route |
-| Other Link props | - | No | Passed to the active router link when a router is available |
+| Prop             | Type              | Required | Description                                                 |
+| ---------------- | ----------------- | -------- | ----------------------------------------------------------- |
+| `to`             | `string`          | Yes      | Target path. Do not include the locale prefix               |
+| `children`       | `React.ReactNode` | Yes      | Link content                                                |
+| `replace`        | `boolean`         | No       | Uses `history.replace` instead of `push`                    |
+| `state`          | `any`             | No       | State passed to the target route                            |
+| Other Link props | -                 | No       | Passed to the active router link when a router is available |
 
 ### Usage
 

package/docs/guides/advanced-features/international/{best-practices.mdx → best-practices.md}

@@ -1,7 +1,3 @@
----
-title: Best Practices
----
-
 # Best Practices
 
 ## Resource File Organization