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

package/docs/en/guides/advanced-features/bff/sdk.mdx

@@ -0,0 +1,116 @@
+# Extend Request SDK
+
+The unified invocation of BFF functions is isomorphic in both CSR and SSR. The request SDK encapsulated by Modern.js relies on the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) on the browser side, and on [node-fetch](https://www.npmjs.com/package/node-fetch) on the server side. However, in actual business scenarios, additional processing may be required for requests or responses, such as:
+
+- Writing authentication information in the request headers
+- Uniform handling of response data or errors
+- Using other methods to send requests when the native fetch function is unavailable on specific platforms
+
+To address these scenarios, Modern.js provides the `configure` function, which offers a series of extension capabilities. You can use it to configure SSR passthrough request headers, add interceptors, or customize the request SDK.
+
+:::caution Note
+The `configure` function needs to be called before all BFF requests are sent to ensure that the default request configuration is overridden.
+:::
+
+```tsx title="routes/page.tsx"
+import { configure } from '@modern-js/plugin-bff/client';
+
+configure({
+  // ...
+});
+
+const Index = () => <div>Hello world</div>;
+export default Index;
+```
+
+## Configuring SSR Passthrough Request Headers
+
+When using both Modern.js SSR and BFF, it is often necessary to pass some request header information from the SSR page request to the BFF service.
+
+For example, imagine a project with a page URL `https://website.com`. This page is rendered using SSR, and in the component, it will call the API endpoint `https://website.com/api/info`, which requires the user's cookie information for authentication. The page needs to pass the `cookie` of the SSR page request to the BFF when requesting this API endpoint.
+
+Currently, the following request headers are automatically passed through in Modern.js:
+
+```ts
+['cookie', 'user-agent', 'x-tt-logid', 'x-tt-stress'];
+```
+
+You can configure additional request headers using `configure`. For example, in the following snippet, Modern.js will automatically pass the `x-uid` information from the SSR page request to the BFF service:
+
+```tsx
+configure({
+  allowedHeaders: ['x-uid'],
+});
+```
+
+## Adding Interceptors
+
+In some business scenarios, you may need to handle requests and responses uniformly. This can be achieved by **configuring interceptors**:
+
+```tsx
+configure({
+  // The `request` here is the default request tool for unified invocation. The `interceptor` function needs to return a new request.
+  // The output of the new request must be the parsed body result.
+  interceptor(request) {
+    return async (url, params) => {
+      const res = await request(url, params);
+      // Interceptors may return Response objects, which need to be manually parsed as JSON
+      if (res instanceof Response) {
+        return res.json();
+      }
+      // If it's already parsed data, return directly
+      return res;
+    };
+  },
+});
+```
+
+## Customizing the Request SDK
+
+If configuring interceptors alone cannot meet your needs and you want to customize the request function, you can also configure it using `configure`:
+
+```tsx
+import nodeFetch from 'node-fetch';
+
+const customFetch = (input: RequestInfo | URL, init: RequestInit) => {
+  const curFetch =
+    process.env.MODERN_TARGET !== 'node'
+      ? fetch
+      : (nodeFetch as unknown as typeof fetch);
+  return curFetch(input, init).then(async res => {
+    const data = await res.json();
+    data.hello = 'hello custom sdk';
+    return data;
+  });
+};
+
+configure({
+  request: customFetch,
+});
+```
+
+There are some conventions when configuring custom request functions:
+
+- The function's parameters should align with the Fetch API or node-fetch in the browser. All unified invocations of BFF functions will send requests via this function.
+- The function's output must be the actual data returned by the API, not a Promise, otherwise, the BFF function will not return data correctly.
+- If it's an SSR project, the function must support sending requests on both the browser and server sides.
+
+Below is an example of using axios to customize a request function:
+
+```tsx title="App.tsx"
+import { configure } from '@modern-js/plugin-bff/client';
+import type { Method, AxiosRequestHeaders as Headers } from 'axios';
+
+configure({
+  async request(...config: Parameters<typeof fetch>) {
+    const [url, params] = config;
+    const res = await axios({
+      url: url as string, // Here we need to use `as` because fetch and axios types are somewhat incompatible
+      method: params?.method as Method,
+      data: params?.body,
+      headers: params?.headers as Headers,
+    });
+    return res.data;
+  },
+});
+```

package/docs/en/guides/advanced-features/bff/upload.mdx

@@ -0,0 +1,7 @@
+# File Upload
+
+BFF combined with runtime framework provides file upload capabilities, supporting integrated calls and pure function manual calls.
+
+import BffUpload from '@site-docs-en/components/bff-upload';
+
+<BffUpload />

package/docs/en/guides/advanced-features/bff.mdx

@@ -0,0 +1,22 @@
+---
+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.
+
+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/en/guides/advanced-features/build-performance.mdx

@@ -0,0 +1,134 @@
+---
+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.
+
+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.
+:::
+
+## 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#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](/en/configure/app/output/source-map.html) for details.

package/docs/en/guides/advanced-features/compatibility.mdx

@@ -0,0 +1,81 @@
+---
+sidebar_position: 6
+---
+
+# 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.
+
+import DefaultBrowserslist from '@site-docs/components/default-browserslist';
+
+<DefaultBrowserslist />
+
+
+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) 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.
+:::
+
+import UpgradeBrowserslist from '@site-docs-en/components/upgrade-browserslist';
+
+<UpgradeBrowserslist />
+
+## 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) 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';
+
+<UAPolyfill />

package/docs/en/guides/advanced-features/international/_meta.json

@@ -0,0 +1,10 @@
+[
+  "quick-start",
+  "configuration",
+  "locale-detection",
+  "resource-loading",
+  "routing",
+  "api",
+  "advanced",
+  "best-practices"
+]

package/docs/en/guides/advanced-features/international/advanced.mdx

@@ -0,0 +1,132 @@
+---
+title: Advanced Usage
+---
+
+# 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.