@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

package/docs/en/components/hono.mdx

@@ -0,0 +1,119 @@
+### Getting Request Context
+
+Sometimes in BFF functions, it's necessary to obtain the request context to handle more logic. In such cases, you can use `useHonoContext` to get it:
+
+```ts title="api/lambda/hello.ts"
+import { useHonoContext } from '@modern-js/plugin-bff/server';
+
+export const get = async () => {
+  const c = useHonoContext();
+  console.info(`access url: ${c.req.url}`);
+  return 'Hello Modern.js';
+};
+```
+
+:::info
+For more details, refer to [useHonoContext](/apis/app/runtime/bff/use-hono-context).
+:::
+
+### Getting Cookies
+
+When getting cookies in BFF functions, you need to get the request context through `useHonoContext`, then use `c.req.header('cookie')` to get the Cookie string and parse it manually:
+
+```ts title="api/lambda/cookies.ts"
+import { Api, Get, useHonoContext } from '@modern-js/plugin-bff/server';
+
+// Helper function to parse Cookie string
+function parseCookies(
+  cookieHeader: string | undefined,
+): Record<string, string> {
+  const cookies: Record<string, string> = {};
+  if (!cookieHeader) return cookies;
+
+  cookieHeader.split(';').forEach(cookie => {
+    const [name, ...rest] = cookie.trim().split('=');
+    if (name) {
+      cookies[name] = rest.join('=');
+    }
+  });
+
+  return cookies;
+}
+
+export const getCookies = Api(Get('/cookies'), async () => {
+  const c = useHonoContext();
+  const cookieHeader = c.req.header('cookie');
+  const cookies = parseCookies(cookieHeader);
+  const token = cookies.token;
+  const sessionId = cookies.sessionId;
+  return {
+    hasToken: !!token,
+    token: token || null,
+    sessionId: sessionId || null,
+  };
+});
+```
+
+:::caution Note
+The `c.req.cookie()` method does not exist in the current version. You need to use `c.req.header('cookie')` to get the Cookie string and parse it manually.
+:::
+
+### Defining BFF Functions
+
+When using Hono as the runtime framework, you can define interfaces through [Api functions](/guides/advanced-features/bff/operators.html):
+
+```ts title="api/lambda/user.ts"
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
+import { z } from 'zod';
+
+const QuerySchema = z.object({
+  id: z.string(),
+});
+
+export const getUser = Api(
+  Get('/user'),
+  Query(QuerySchema),
+  async ({ query }) => {
+    return {
+      id: query.id,
+      name: 'Modern.js',
+      email: 'modernjs@bytedance.com',
+    };
+  },
+);
+```
+
+:::info
+For more details about Api functions and operators, refer to [Creating Extensible BFF Functions](/guides/advanced-features/bff/operators.html).
+:::
+
+### Using Middleware
+
+Hono supports a rich middleware ecosystem, and you can use middleware in BFF functions:
+
+```ts title="api/lambda/user.ts"
+import { Api, Get, Middleware } from '@modern-js/plugin-bff/server';
+
+export const getUser = Api(
+  Get('/user'),
+  Middleware(async (c, next) => {
+    // You can access Hono's Context in middleware
+    c.res.headers.set('X-Powered-By', 'Modern.js');
+    await next();
+  }),
+  async () => {
+    return {
+      name: 'Modern.js',
+      email: 'modernjs@bytedance.com',
+    };
+  },
+);
+```
+
+:::info
+For more details about middleware, refer to [Creating Extensible BFF Functions](/guides/advanced-features/bff/operators.html#middleware).
+:::
+
+### More Hono Documentation
+
+For more detailed information about Hono, please refer to the [Hono official documentation](https://hono.dev/).

package/docs/en/components/init-app.mdx

@@ -1,37 +1,60 @@
-`@modern-js/create` provides an interactive Q & A interface to initialize the project based on the results, with initialization performed according to the default settings:
+Modern.js provides the `@modern-js/create` tool to create projects. It does not require global installation and can be run on-demand using `npx`.
+
+You can create a project in an existing empty directory:
+
+```bash
+mkdir myapp && cd myapp
+npx @modern-js/create@latest
+```
+
+You can also create a project directly in a new directory:
 
 ```bash
-? Please select the programming language: TS
-? Please select the package manager: pnpm
+npx @modern-js/create@latest myapp
 ```
 
-After create the project, Modern.js will automatically install dependencies and create a git repository.
+`@modern-js/create` will directly create the application without providing an interactive Q & A interface:
 
 ```bash
-[INFO] dependencies are automatically installed
-[INFO] git repository has been automatically created
-[INFO] Success！
-You can run the following command in the directory of the new project:
-pnpm run dev          # Starting dev server
-pnpm run build        # Build the app for production
-pnpm run serve        # Preview the production build locally
-pnpm run lint         # Run ESLint and automatically fix problems
-pnpm run new          # Enable optional features or add a new entry
+🚀 Welcome to Modern.js
+
+📦 Creating project "myapp"...
+
+✨ Project created successfully! 🎉
+
+📋 Next, you can run the following commands:
+
+📁 Enter the project directory:
+
+  cd myapp
+
+🔧 Initialize Git repository:
+
+  git init
+
+📥 Install project dependencies:
+
+  pnpm install
+
+⚡ Start the development server:
+
+  pnpm start
 ```
 
 Now, the project structure is as follows:
 
 ```
 .
+├── biome.json
+├── modern.config.ts
+├── package.json
+├── README.md
 ├── src
 │   ├── modern-app-env.d.ts
+│   ├── modern.runtime.ts
 │   └── routes
 │       ├── index.css
 │       ├── layout.tsx
 │       └── page.tsx
-├── modern.config.ts
-├── package.json
-├── pnpm-lock.yaml
-├── README.md
 └── tsconfig.json
 ```

package/docs/en/components/international/custom-instance-code.mdx

@@ -0,0 +1,16 @@
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+// Create custom instance
+const customI18n = i18next.createInstance({
+  // Custom configuration
+});
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance: customI18n,
+  },
+});
+```
+

package/docs/en/components/international/init-options-desc.mdx

@@ -0,0 +1 @@
+`initOptions` will be passed to i18next's `init` method and supports all i18next configuration options:

package/docs/en/components/international/install-command.mdx

@@ -0,0 +1,23 @@
+```bash
+pnpm add @modern-js/plugin-i18n i18next react-i18next
+```
+
+:::tip Version Consistency
+Make sure the version of `@modern-js/plugin-i18n` matches the version of `@modern-js/app-tools` in your project. All Modern.js official packages are released with a uniform version number, and version mismatches may cause compatibility issues.
+
+Check the version of `@modern-js/app-tools` first, then install the same version of `@modern-js/plugin-i18n`:
+
+```bash
+# Check the current version of @modern-js/app-tools
+pnpm list @modern-js/app-tools
+
+# Install the same version of @modern-js/plugin-i18n
+pnpm add @modern-js/plugin-i18n@<version> i18next react-i18next
+```
+
+:::
+
+:::info
+`i18next` and `react-i18next` are peer dependencies and need to be installed manually.
+
+:::

package/docs/en/components/international/instance-code.mdx

@@ -0,0 +1,26 @@
+Create the `src/modern.runtime.ts` file and configure i18n runtime options:
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+// It's recommended to create a new i18next instance to avoid using the global default instance
+const i18nInstance = i18next.createInstance();
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance: i18nInstance,
+    initOptions: {
+      fallbackLng: 'en',
+      supportedLngs: ['zh', 'en'],
+    },
+  },
+});
+```
+
+:::info
+`modern.runtime.ts` is a runtime configuration file used to configure i18next initialization options. Even for the most basic configuration, it's recommended to create this file to ensure the plugin works correctly.
+
+It's recommended to use `i18next.createInstance()` to create a new instance instead of directly using the default exported `i18next`. This avoids global state pollution and ensures each application has an independent i18n instance.
+
+:::

package/docs/en/components/international/introduce.mdx

@@ -0,0 +1,2 @@
+`@modern-js/plugin-i18n` is Modern.js's internationalization plugin, built on top of [i18next](https://www.i18next.com/) and [react-i18next](https://react.i18next.com/), providing a complete internationalization solution for Modern.js applications.
+

package/docs/en/components/module-federation.mdx

@@ -1,7 +1,7 @@
-Module Federation (MF) is a feature of Webpack. It allows a JavaScript application to dynamically load code from another application, and in the process, share dependencies. If an application consuming a federated module does not have a dependency needed by the federated code, Webpack will download the missing dependency from that federated build origin.
+Module Federation (MF) is a technology solution that allows multiple JavaScript applications to share code and resources. Similar to microservices architecture on the server side, it allows you to split large applications into multiple independent smaller applications that can be developed, tested, and deployed independently, while dynamically loading modules from other applications at runtime.
 
-This allows for the creation of micro-frontend-style applications, where multiple systems can share code and be dynamically updated without having to rebuild the entire application.
+Module Federation solves the problem of code duplication across multiple frontend applications. In the traditional approach, if multiple applications need to use the same components or utility functions, you would need to duplicate this code in each application, leading to code duplication, high maintenance costs, and larger application sizes. With Module Federation, you can place common code in one application and have other applications load it dynamically as needed, enabling code sharing and reducing duplication.
 
-Modern.js provides an example project for Module Federation. Please refer to [module-federation-examples - modernjs](https://github.com/module-federation/module-federation-examples/tree/db5bdbeee56f779999a2c591fc553eb94eb20b36/modernjs).
+Module Federation 2.0 supports [Rspack](https://rspack.rs/) build tools, and provides enhanced features such as dynamic type hints, Manifest, Federation Runtime, runtime plugin system, and Chrome Devtools support for better development experience and debugging capabilities. You can visit the [Module Federation official documentation](https://module-federation.io/) to learn more.
 
-You can also read the [webpack Module Federation documentation](https://webpack.js.org/concepts/module-federation/) to learn more concepts.
+Modern.js provides an example project for Module Federation. Please refer to [module-federation-examples - modernjs](https://github.com/module-federation/module-federation-examples/tree/db5bdbeee56f779999a2c591fc553eb94eb20b36/modernjs).

package/docs/en/components/nodeVersion.mdx

@@ -1,4 +1,4 @@
-Before getting started, you will need to install [Node.js](https://nodejs.org/), and ensure that your Node.js version is higher than 18.20.8. **We recommend using the LTS version of Node.js 22.**
+Before getting started, you will need to install [Node.js](https://nodejs.org/), and ensure that your Node.js version is not lower than v20.19.5. **We recommend using the LTS version of Node.js 22.**
 
 You can check the currently used Node.js version with the following command:
 
@@ -6,7 +6,7 @@ You can check the currently used Node.js version with the following command:
 node -v
 ```
 
-If you do not have Node.js installed in your current environment, or the installed version is lower than 18.20.8, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install the required version.
+If you do not have Node.js installed in your current environment, or the installed version is lower than v20.19.5, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install the required version.
 
 Here is an example of how to install the Node.js 22 LTS version via nvm:
 
@@ -26,7 +26,3 @@ Both nvm and fnm are Node.js version management tools. Relatively speaking, nvm
 :::
 
 Additionally, after installing nvm or fnm, when there is a `.nvmrc` file containing `lts/jod` in the repository's root directory, the system will automatically install or switch to the correct Node.js version upon entering the repository.
-
-:::warning
-Modern.js currently still supports Node 16, but will officially terminate support for Node.js 16 in June 2025. To ensure a smooth transition for your project, please complete the Node.js version upgrade before June 2025.
-:::

package/docs/en/components/prerequisites.mdx

@@ -9,7 +9,7 @@ import NodeVersion from '@site-docs-en/components/nodeVersion.mdx';
 It is recommended to use [pnpm](https://pnpm.io/installation) to manage dependencies:
 
 ```bash
-npm install -g pnpm@9
+npm install -g pnpm@10
 ```
 
 :::note

package/docs/en/components/ua-polyfill.mdx

@@ -1,19 +1,23 @@
-
 ### Polyfill At Runtime
 
 Modern.js also provides a runtime Polyfill solution based on browser [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) information, which has the following advantages over Babel:
 
-- It will not be inserted into the code, reducing the code .
-- The same browser will share a Polyfill code. Therefore, with more and more projects, the UA-based Polyfill code will be delivered faster and faster.
+- It will not be inserted into the code, and only delivers Polyfill code on-demand based on the device accessing the page, reducing the overall code size.
+- The same browser will share a Polyfill code. Therefore, with more and more projects, the UA-based Polyfill code will be delivered faster and faster, with overall speed exceeding conventional solutions.
 
-exec `pnpm run new` to enable this features:
+Modern.js provides the `@modern-js/plugin-polyfill` plugin to implement this feature. You can enable it by installing the plugin:
 
-```bash
-? Please select the operation you want: Enable features
-? Please select the feature name: Enable UA-based Polyfill Feature
-```
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm install @modern-js/plugin-polyfill',
+    yarn: 'yarn add @modern-js/plugin-polyfill',
+    pnpm: 'pnpm add @modern-js/plugin-polyfill',
+  }}
+/>
 
-After executing the command, register the Polyfill plugin in `modern.config.ts`:
+Then register the Polyfill plugin in `modern.config.ts`:
 
 ```ts title="modern.config.ts"
 import { polyfillPlugin } from '@modern-js/plugin-polyfill';
@@ -23,18 +27,18 @@ export default defineConfig({
 });
 ```
 
-After configuring `output.polyfill` as `ua` and executing `pnpm run build & & pnpm run serve` to start the server, visiting the page can see that the HTML artifacts contains the following script:
+After configuring `output.polyfill` as `ua` and executing `pnpm run build && pnpm run serve` to start the server, visiting the page can see that the HTML artifacts contains the following script:
 
 ```js
 <script src="/__polyfill__" crossorigin></script>
 ```
 
-Visit the page `http://localhost:8080/__polyfill__` on Chrome 51 to see:
+When accessing the page on Chrome 51, you can see the content returned by `http://localhost:8080/__polyfill__` as follows:
 
 ![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
 
 :::caution
 This feature only works when using Modern.js built-in Web Server.
 
-If you need to customize the HTML template, please refer to [HTML Template](/guides/basic-features/html.html). Manually modifying the template through html.template / tools.html will cause this feature not work.
+If you need to customize the HTML template, please refer to [HTML Template](/guides/basic-features/html.html). Manually modifying the template through `html.template` or `tools.html` may cause this feature to not work correctly.
 :::

package/docs/en/configure/_meta.json

@@ -32,20 +32,20 @@
   },
   {
     "type": "dir",
-    "name": "app/server",
-    "label": "server",
+    "name": "app/resolve",
+    "label": "resolve",
     "collapsed": true
   },
   {
     "type": "dir",
-    "name": "app/output",
-    "label": "output",
+    "name": "app/server",
+    "label": "server",
     "collapsed": true
   },
   {
     "type": "dir",
-    "name": "app/deploy",
-    "label": "deploy",
+    "name": "app/output",
+    "label": "output",
     "collapsed": true
   },
   "app/plugins",
@@ -73,6 +73,5 @@
     "label": "experiments",
     "collapsed": true
   },
-  "app/builder-plugins",
-  "app/auto-load-plugin"
+  "app/builder-plugins"
 ]

package/docs/en/configure/app/bff/cross-project.mdx

@@ -0,0 +1,24 @@
+---
+title: crossProject
+---
+
+# bff.crossProject
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+This configuration is used to enable BFF cross-project invocation functionality. When enabled, the current project can be used as a BFF producer, generating an SDK that can be directly called by other projects.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    crossProject: true,
+  },
+});
+```
+
+For detailed configuration and usage of BFF cross-project invocation, please refer to the [BFF Cross-Project Invocation Guide](/guides/advanced-features/bff/cross-project.html).

package/docs/en/configure/app/builder-plugins.mdx

@@ -16,8 +16,7 @@ Rsbuild is the build tool of Modern.js, please read [Build Engine](/guides/conce
 This option **is used to configure the Rsbuild plugins**. If you need to configure other types of plugins, please select the corresponding configs:
 
 - Use [plugins](/configure/app/plugins) to configure Modern.js framework plugins.
-- Use [tools.bundlerChain](/configure/app/tools/bundler-chain) to configure Rspack or webpack plugins.
-- Use [tools.babel](/configure/app/tools/babel) to configure Babel plugins.
+- Use [tools.bundlerChain](/configure/app/tools/bundler-chain) to configure Rspack plugins.
 
 ## When to use
 

package/docs/en/configure/app/dev/lazy-compilation.mdx

@@ -0,0 +1,45 @@
+---
+title: lazyCompilation
+---
+
+# dev.lazyCompilation
+
+- **Type:**
+
+```ts
+type LazyCompilationOptions =
+  | boolean
+  | {
+      /**
+       * Enable lazy compilation for entries.
+       */
+      entries?: boolean;
+      /**
+       * Enable lazy compilation for dynamic imports.
+       */
+      imports?: boolean;
+      /**
+       * Specify which imported modules should be lazily compiled.
+       */
+      test?: RegExp | ((m: Module) => boolean);
+      /**
+       * The path to a custom runtime code that overrides the default lazy compilation client.
+       */
+      client?: string;
+      /**
+       * Tells the client the server URL that needs to be requested.
+       */
+      serverUrl?: string;
+    };
+```
+
+- **Default:** `false`
+
+Enable lazy compilation (compilation on demand), implemented based on Rspack's [lazy compilation](https://rspack.rs/guide/features/lazy-compilation) feature.
+
+import RsbuildLink from '@site/src/components/RsbuildLink';
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to <RsbuildLink configName="dev.lazyCompilation"/>。
+In Rspack build mode,
+:::