@modern-js/app-tools 3.7.0 → 3.8.0

package/docs/guides/advanced-features/bff/upload.md

@@ -0,0 +1,101 @@
+# 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:
+
+```ts title="api/lambda/upload.ts"
+export const post = async ({ formData }: { formData: Record<string, any> }) => {
+  console.info('formData:', formData);
+  // do somethings
+  return {
+    data: {
+      code: 0,
+    },
+  };
+};
+```
+
+:::tip
+The `formData` parameter in the interface processing function can access files uploaded from the client side. It is an `Object` where the keys correspond to the field names used during the upload.
+:::
+
+### Integrated Calling
+
+Next, directly import and call the function in `src/routes/upload/page.tsx`:
+
+```tsx title="routes/upload/page.tsx"
+import { post } from '@api/upload';
+import React, { type JSX } from 'react';
+
+export default (): JSX.Element => {
+  const [file, setFile] = React.useState<FileList | null>();
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    setFile(e.target.files);
+  };
+
+  const handleSubmit = async (e: React.MouseEvent<HTMLButtonElement>) => {
+    e.preventDefault();
+    const formData = new FormData();
+    if (file) {
+      for (let i = 0; i < file.length; i++) {
+        formData.append('images', file[i]);
+      }
+      post({
+        formData,
+      });
+    }
+  };
+
+  return (
+    <div>
+      <input multiple type="file" onChange={handleChange} />
+      <button onClick={handleSubmit}>upload</button>
+    </div>
+  );
+};
+```
+
+:::tip
+Note: The input parameter type must be `{ formData: FormData }` for the upload to succeed.
+:::
+
+### Manual Calling
+
+You can manually upload files using the `fetch API`, when calling `fetch`, set the `body` as `FormData` type and submit a post request.
+
+```tsx title="routes/upload/page.tsx"
+import React from 'react';
+
+export default (): JSX.Element => {
+  const [file, setFile] = React.useState<FileList | null>();
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    setFile(e.target.files);
+  };
+
+  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData();
+    if (file) {
+      for (let i = 0; i < file.length; i++) {
+        formData.append('images', file[i]);
+      }
+      await fetch('/api/upload', {
+        method: 'POST',
+        body: formData,
+      });
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input multiple type="file" onChange={handleChange} />
+      <button type="submit">upload</button>
+    </form>
+  );
+};
+```

package/docs/guides/advanced-features/bff.md

@@ -0,0 +1,18 @@
+# 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.
+
+The main problems it tries to solve include:
+
+- Aggregation, mapping, clipping, and proxying of lower-level APIs according to their own business needs.
+- Cache data for some specific scenarios to improve performance and thus improve user experience.
+- Quickly development of new products based on existing interfaces.
+- Interface with third-party systems, such as login authentication.
+
+Modern.js officially supported the BFF and provided the **Integrated BFF** to further strengthen the BFF's capabilities, mainly including the following capabilities:
+
+- Quick development and debugging go live, running, building, and deploying BFF code in the same project.
+- Minimal pure function call, directly import BFF function on the front end, and can be automatically converted into HTTP request when called.
+- No private protocol, follow RESTful API specification, all BFF interfaces are standardized.
+- Full TypeScript support.
+- Meet user preferences and support multi-frame extension writing.

package/docs/guides/advanced-features/build-performance.md

@@ -0,0 +1,130 @@
+# Improve Build Performance
+
+Modern.js optimizes build performance by default, but as the project becomes larger, you may encounter some build performance problems.
+
+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.md) can also be used to improve build performance, so we won't repeat them here.
+:::
+
+## General optimization strategy
+
+The following are some general optimization strategies, which can speed up the development build and production build, and some of them also optimize the bundle size.
+
+### Upgrade Node.js version
+
+In general, updating Node.js to the latest [LTS release](https://github.com/nodejs/release#release-schedule) will help improve build performance.
+
+Modern.js requires Node.js version >= 20.19.5. We strongly recommend using the latest LTS version (such as Node.js 22 LTS) for the best build performance.
+
+You can switch to the latest LTS version by following these steps:
+
+```bash
+# Install the latest LTS version (e.g., Node.js 22)
+nvm install --lts
+
+# Switch to the latest LTS version
+nvm use --lts
+
+# Set the latest LTS version as the default
+nvm alias default lts/*
+
+# View Node version
+node -v
+```
+
+Or install Node.js 22 LTS specifically:
+
+```bash
+# Install Node.js 22 LTS
+nvm install 22 --lts
+
+# Switch to Node.js 22
+nvm use 22
+
+# Set Node.js 22 as the default version
+nvm alias default 22
+
+# View Node version
+node -v
+```
+
+## Development optimization strategies
+
+The following are strategies for improve build performance in development environment.
+
+### Adjust Source Map format
+
+In order to provide a good debugging experience, Modern.js uses the `cheap-module-source-map` format Source Map by default in the development environment, which is a high-quality Source Map format and will bring certain performance overhead.
+
+You can improve build speed by adjusting the source map format of your development environment.
+
+For example to disable Source Map:
+
+```js
+export default {
+  tools: {
+    bundlerChain(chain, { env }) {
+      if (env === 'development') {
+        chain.devtool(false);
+      }
+    },
+  },
+};
+```
+
+Or set the source map format of the development environment to the cheapest `eval` format:
+
+```js
+export default {
+  tools: {
+    bundlerChain(chain, { env }) {
+      if (env === 'development') {
+        chain.devtool('eval');
+      }
+    },
+  },
+};
+```
+
+> For detailed differences between different Source Map formats, see [rspack - devtool](https://rspack.rs/config/devtool).
+
+### Adjust Browserslist for development
+
+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:
+
+```json
+{
+  "browserslist": {
+    "production": [">0.2%", "not dead", "not op_mini all"],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}
+```
+
+Note that this strategy can lead to some differences in the build result of development production environment.
+
+## Production optimization strategies
+
+The following are strategies for improve build performance in production environment.
+
+### Disable Source Map
+
+If your project does not need Source Map in the production, you can turn it off through the `sourcemap` config to improve the build speed.
+
+```js
+export default {
+  output: {
+    sourceMap: false,
+  },
+};
+```
+
+See [output.sourceMap](/configure/app/output/source-map.md) for details.

package/docs/guides/advanced-features/compatibility.md

@@ -0,0 +1,120 @@
+# Browser Compatibility
+
+## Browserslist Configuration
+
+Modern.js supports three ways to set the range of browsers that a web application needs to support.
+
+### Method 1: Configure via `.browserslistrc` File
+
+Modern.js supports setting the range of browsers that a web application needs to support. You can set the [Browserslist](https://browsersl.ist/) values in the `.browserslistrc` file.
+
+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.
+
+```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.
+
+### Method 2: Configure via package.json
+
+You can also configure browserslist by setting the `browserslist` field in the `package.json` file:
+
+```json title="package.json"
+{
+  "browserslist": [
+    "chrome >= 87"
+    // Other browser configurations...
+  ]
+}
+```
+
+### Method 3: Configure via `output.overrideBrowserslist`
+
+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 {
+  output: {
+    overrideBrowserslist: [
+      'chrome >= 87',
+      // Other browser configurations...
+    ],
+  },
+};
+```
+
+### Configuration Priority
+
+The `overrideBrowserslist` configuration has a higher priority than the `.browserslistrc` file and the `browserslist` field in package.json.
+
+In most scenarios, it is recommended to prioritize using the `.browserslistrc` file rather than the `overrideBrowserslist` configuration because the `.browserslistrc` file is the officially defined configuration file, has better general applicability, and can be recognized by other libraries in the community.
+
+:::tip
+Please refer to [Rsbuild - Setting Browser Range](https://v2.rsbuild.rs/zh/guide/advanced/browserslist) for more information.
+:::
+
+
+## Polyfill
+
+### Compile-time Polyfill
+
+Modern.js by default injects corresponding polyfill code at compile time through [core-js](https://github.com/zloirock/core-js).
+
+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.md) to `usage`. This way, Babel will only inject polyfill code based on the syntax used in the code during compilation.
+
+:::
+
+### 运行时按需 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 产物中包含如下脚本:
+
+```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.md

@@ -0,0 +1,128 @@
+# Advanced Usage
+
+## SSR Scenarios
+
+In SSR scenarios, the plugin detects the language on the server, loads translation resources, and injects the result into the page. The client reuses it directly to avoid language flicker.
+
+**Complete configuration:**
+
+```ts
+// modern.config.ts
+export default defineConfig({
+  server: {
+    ssr: true,
+  },
+  plugins: [
+    appTools(),
+    i18nPlugin({
+      localeDetection: {
+        localePathRedirect: true,
+        i18nextDetector: true,
+        languages: ['zh', 'en'],
+        fallbackLanguage: 'en',
+        detection: {
+          order: ['path', 'cookie', 'header'],
+          lookupHeader: 'accept-language',
+          caches: ['cookie'],
+        },
+      },
+      backend: {
+        loadPath: '/locales/{{lng}}/{{ns}}.json',
+      },
+    }),
+  ],
+});
+```
+
+Server-side language detection priority: URL path -> Cookie -> `Accept-Language` request header -> `fallbackLanguage`.
+
+**Route configuration (file-system routes):**
+
+```
+routes/
+└── [lang]/
+    ├── layout.tsx
+    └── page.tsx
+```
+
+In SSR scenarios, the language detected on the server is written to `window._SSR_DATA`. The client reads it directly and does not detect again, ensuring both sides use the same language.
+
+## Multiple Entries
+
+Different entries can use different language lists, detection methods, and resource paths:
+
+```ts
+// modern.config.ts
+i18nPlugin({
+  localeDetection: {
+    // Global defaults
+    localePathRedirect: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+
+    // Per-entry overrides
+    localeDetectionByEntry: {
+      admin: {
+        localePathRedirect: false, // admin does not use path prefixes
+        languages: ['en'],         // admin only supports English
+      },
+      mobile: {
+        languages: ['zh', 'en', 'ja'], // mobile supports more languages
+      },
+    },
+  },
+  backend: {
+    loadPath: '/locales/{{lng}}/{{ns}}.json', // Global default path
+
+    // Per-entry overrides
+    backendOptionsByEntry: {
+      admin: {
+        loadPath: '/admin/locales/{{lng}}/{{ns}}.json',
+      },
+      mobile: {
+        loadPath: '/mobile/locales/{{lng}}/{{ns}}.json',
+      },
+    },
+  },
+});
+```
+
+## Custom i18next Instance
+
+By default, the plugin uses an internally created i18next instance. If you need deeper customization, such as custom plugins or preconfigured options, pass a custom instance through runtime configuration:
+
+```ts
+// src/i18n.ts
+import i18next from 'i18next';
+
+const customI18n = i18next.createInstance();
+// You can use custom plugins here.
+// customI18n.use(MyPlugin);
+
+export default customI18n;
+```
+
+```ts
+// src/modern.runtime.ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import customI18n from './i18n';
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance: customI18n,
+    initOptions: {
+      fallbackLng: 'en',
+      supportedLngs: ['zh', 'en'],
+    },
+  },
+});
+```
+
+## Language Switching Behavior
+
+When `changeLanguage` is called to switch language:
+
+- **Translation update**: All components that use `t()` re-render automatically. No manual refresh is needed.
+- **URL update** (when `localePathRedirect` is enabled): Updates the URL with `history.pushState`, without triggering a page refresh and without affecting browser back/forward history.
+- **Cache update**: Writes to Cookie or LocalStorage based on the `caches` configuration, so the language choice is restored on the next visit.
+- **When path prefixes are not enabled**: Only the i18next instance and cache are updated. The URL stays unchanged.