@modern-js/main-doc 2.69.5 → 3.0.0-alpha.0

package/docs/en/{_meta.json → _nav.json}

@@ -20,7 +20,7 @@
     "activeMatch": "/apis/"
   },
   {
-    "text": "tutorials",
+    "text": "Examples",
     "link": "/tutorials/foundations/introduction",
     "activeMatch": "/tutorials/"
   },
@@ -28,5 +28,9 @@
     "text": "community",
     "link": "/community/showcase",
     "activeMatch": "/community/"
+  },
+  {
+    "text": "Modern.js 2.x Docs",
+    "link": "https://modernjs.dev/guides/get-started/introduction.html"
   }
 ]

package/docs/en/apis/app/commands.mdx

@@ -108,7 +108,7 @@ Open the above HTML file in the browser, you can see the tile diagram of the bun
 
 The `modern new` command is used to enable features in an existing project.
 
-For example, add application entry, enable some optional features such as Tailwind CSS, micro frontend, etc.
+For example, add application entry, enable some optional features such as BFF, micro frontend, etc.
 
 ```bash
 Usage: modern new [options]
@@ -142,8 +142,7 @@ In the project, execute the `new` command to enable features as follows:
 $ npx modern new
 ? Please select the operation you want: Enable Features
 ? Please select the feature name: (Use arrow keys)
-❯ Enable Tailwind CSS
-  Enable BFF
+❯ Enable BFF
   Enable SSG
   Enable Micro Frontend
 ```

package/docs/en/apis/app/hooks/src/entry.mdx

@@ -5,10 +5,6 @@ sidebar_position: 4
 
 # entry.[tj]sx
 
-:::info
-Using this file requires enabling [source.enableCustomEntry](/configure/app/source/enable-custom-entry).
-:::
-
 Normally, the [`routes/`](/apis/app/hooks/src/routes.html) and [`App.[tj]sx`](/apis/app/hooks/src/app) hook files can meet our needs. When we need to add custom behavior before component rendering or take full control of the webpack packaging entry, we can create `entry.[tj]s` file in the src or entry directory. Here are two cases for discussion。
 
 ## Add custom behavior before Render
@@ -22,7 +18,7 @@ import { render } from '@modern-js/runtime/browser';
 const ModernRoot = createRoot();
 
 async function beforeRender() {
-   // todo
+  // todo
 }
 
 beforeRender().then(() => {

package/docs/en/apis/app/hooks/src/entry.server.mdx

@@ -5,10 +5,6 @@ sidebar_position: 5
 
 # entry.server.[tj]sx
 
-:::info
-Using this file requires enabling [source.enableCustomEntry](/configure/app/source/enable-custom-entry).
-:::
-
 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"
@@ -35,7 +31,10 @@ export default createRequestHandler(handleRequest);
 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 } from '@modern-js/runtime/ssr/server';
+import {
+  renderString,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
 import type { HandleRequest } from '@modern-js/runtime/ssr/server';
 
 const handleRequest: HandleRequest = async (request, ServerRoot, options) => {

package/docs/en/apis/app/hooks/src/routes.mdx

@@ -4,7 +4,7 @@ sidebar_position: 2
 ---
 # routes/
 
-The identifier for the entry point when the application uses [Conventional Routing](guides/basic-features/routes.html#conventional-routing).
+The identifier for the entry point when the application uses [Conventional Routing](/guides/basic-features/routes/routes#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.
 
@@ -85,6 +85,6 @@ export default () => {
 ```
 
 :::note
-`<Outlet>` is a new API in React Router 6. For details, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+`<Outlet>` is a new API in React Router 7. For details, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
 
 :::

package/docs/en/apis/app/runtime/_meta.json

@@ -5,24 +5,12 @@
     "label": "Core",
     "collapsed": true
   },
-  {
-    "type": "dir",
-    "name": "app",
-    "label": "App",
-    "collapsed": true
-  },
   {
     "type": "dir",
     "name": "router",
     "label": "Router",
     "collapsed": true
   },
-  {
-    "type": "dir",
-    "name": "model",
-    "label": "Model",
-    "collapsed": true
-  },
   {
     "type": "dir",
     "name": "ssr",
@@ -35,12 +23,6 @@
     "label": "BFF",
     "collapsed": true
   },
-  {
-    "type": "dir",
-    "name": "web-server",
-    "label": "Web Server",
-    "collapsed": true
-  },
   {
     "type": "dir",
     "name": "utility",

package/docs/en/apis/app/runtime/bff/use-hono-context.mdx

@@ -8,7 +8,7 @@ Used to obtain Hono context in an integrated BFF function.
 ## Usage
 
 ```ts
-import { useHonoContext } from '@modern-js/plugin-bff/hono';
+import { useHonoContext } from '@modern-js/plugin-bff/server';
 ```
 
 ## Function Signature
@@ -20,7 +20,7 @@ import { useHonoContext } from '@modern-js/plugin-bff/hono';
 Developers can use `context` to obtain more request information, such as setting response headers:
 
 ```ts
-import { useHonoContext } from '@modern-js/plugin-bff/hono';
+import { useHonoContext } from '@modern-js/plugin-bff/server';
 
 export async function get() {
   const c = useHonoContext();

package/docs/en/apis/app/runtime/router/router.mdx

@@ -6,7 +6,7 @@ sidebar_position: 1
 # router
 
 :::info
-The router solution based on [react-router 6](https://reactrouter.com/).
+The router solution based on [react-router v7](https://reactrouter.com/).
 
 :::
 

package/docs/en/apis/app/runtime/utility/css-in-js.mdx

@@ -1,6 +1,7 @@
 ---
 title: CSS-In-JS API
 ---
+
 # CSS-In-JS API
 
 Use Style Component to write CSS.
@@ -8,7 +9,7 @@ Use Style Component to write CSS.
 ## Usage
 
 ```ts
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 ```
 
 ## Function Signature
@@ -18,7 +19,7 @@ see [styled-component API](https://styled-components.com/docs/api).
 ## Example
 
 ```tsx
-import styled from '@modern-js/runtime/styled';
+import styled from '@modern-js/plugin-styled-components/styled';
 
 const Button = styled.button`
   background: palevioletred;

package/docs/en/community/blog/v2-release-note.mdx

@@ -232,8 +232,6 @@ Modern.js 中的部分代码实现参考了社区中的开源项目，我们对
 
 - `@modern-js/bundle-require`: 修改自 [bundle-require](https://github.com/egoist/bundle-require)。
 - `@modern-js/plugin`: hook API 的实现参考了 [farrow-pipeline](https://github.com/farrow-js/farrow/tree/master/packages/farrow-pipeline)。
-- `@modern-js/builder`: moduleScope 和 fileSize 插件参考了 [create-react-app](https://github.com/facebook/create-react-app)，TsConfigPathsPlugin 参考了 [tsconfig-paths-webpack-plugin](https://github.com/dividab/tsconfig-paths-webpack-plugin)，generateMetaTags 函数参考了 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin)。
-- `@modern-js/plugin-testing`: jest runner 参考了 [jest-cli](https://github.com/facebook/jest/blob/fdc74af37235354e077edeeee8aa2d1a4a863032/packages/jest-cli/src/cli/index.ts#L21)。
 - `@modern-js/plugin-data-loader`: 部分实现参考了 [remix](https://github.com/remix-run/remix)。
 
 ## 最后

package/docs/en/community/contributing-guide.mdx

@@ -15,7 +15,7 @@ own GitHub account and then [clone](https://help.github.com/articles/cloning-a-r
 
 ### Install Node.js
 
-We recommend using Node.js 18. You can check your currently used Node.js version with the following command:
+We recommend using Node.js 22. You can check your currently used Node.js version with the following command:
 
 ```bash
 node -v
@@ -23,17 +23,17 @@ node -v
 
 If you do not have Node.js installed in your current environment, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install it.
 
-Here is an example of how to install the Node.js 18 LTS version via nvm:
+Here is an example of how to install the Node.js 22 LTS version via nvm:
 
 ```bash
-# Install the LTS version of Node.js 18
-nvm install 18 --lts
+# Install the LTS version of Node.js 22
+nvm install 22 --lts
 
-# Make the newly installed Node.js 18 as the default version
-nvm alias default 18
+# Make the newly installed Node.js 22 as the default version
+nvm alias default 22
 
-# Switch to the newly installed Node.js 18
-nvm use 18
+# Switch to the newly installed Node.js 22
+nvm use 22
 ```
 
 ### Install pnpm
@@ -125,7 +125,7 @@ pnpm run reset
 
 If you've fixed a bug or added code that should be tested, then add some tests.
 
-You can add unit test cases in the `<PACKAGE_DIR>/tests` folder. The test syntax is based on [Jest](https://jestjs.io/) and [Vitest](https://vitest.dev/).
+You can add unit test cases in the `<PACKAGE_DIR>/tests` folder. The test syntax is based on [Jest](https://jestjs.io/) and [Rstest](https://rstest.rs/).
 
 ### Run Unit Tests
 
@@ -185,9 +185,7 @@ You can find all the documentation in the `packages/document` folder:
 ```bash
 root
 └─ packages
-   └─ document
-       ├─ main-doc       # Documentation for Modern.js Framework
-       └─ module-doc     # Documentation for Modern.js Module
+   └─ document  # Documentation for Modern.js Framework
 ```
 
 This website is built with Rspress, the document content can be written using markdown or mdx syntax. You can refer to the [Rspress Website](https://rspress.rs/) for detailed usage.

package/docs/en/components/bff-upload.mdx

@@ -23,9 +23,10 @@ The `formData` parameter in the interface processing function can access files u
 ### Integrated Calling
 
 Next, directly import and call the function in `src/routes/upload/page.tsx`:
+
 ```tsx title="routes/upload/page.tsx"
-import { upload } from '@api/upload';
-import React from 'react';
+import { post } from '@api/upload';
+import React, { type JSX } from 'react';
 
 export default (): JSX.Element => {
   const [file, setFile] = React.useState<FileList | null>();
@@ -34,27 +35,30 @@ export default (): JSX.Element => {
     setFile(e.target.files);
   };
 
-  const handleUpload = () => {
-    if (!file) {
-      return;
+  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,
+      });
     }
-    upload({
-      files: {
-        images: file,
-      },
-    });
   };
 
   return (
     <div>
       <input multiple type="file" onChange={handleChange} />
-      <button onClick={handleUpload}>upload</button>
+      <button onClick={handleSubmit}>upload</button>
     </div>
   );
 };
 ```
+
 :::tip
-Note: The input type must be `{ formData: FormData }` for the upload to succeed.
+Note: The input parameter type must be `{ formData: FormData }` for the upload to succeed.
 :::
 
 

package/docs/en/components/build-output.mdx

@@ -0,0 +1,45 @@
+To build the production artifacts of the project, run `pnpm run build` in the project:
+
+```bash
+$ pnpm run build
+
+> modern build
+
+  Modern.js Framework
+
+info    Starting production build...
+info    Type checker is enabled. It may take some time.
+ready   Client compiled in 6.19 s
+info    Production file sizes:
+
+  File                                       Size        Gzipped
+  dist/routes-manifest.json                  0.74 kB     0.28 kB
+  dist/static/css/async/page.d7915515.css    1.4 kB      0.69 kB
+  dist/static/js/main.5ae469e7.js            3.0 kB      1.3 kB
+  dist/html/index/index.html                  6.0 kB      2.6 kB
+  dist/static/js/async/page.ddc8a4c1.js      19.2 kB     6.7 kB
+  dist/static/js/34.171fffdb.js              21.3 kB     7.1 kB
+  dist/static/js/lib-router.8995a55e.js      55.3 kB     18.1 kB
+  dist/static/js/lib-lodash.53ec3384.js      71.4 kB     24.8 kB
+  dist/static/js/lib-react.b5856db9.js       140.0 kB    45.2 kB
+  dist/static/js/lib-polyfill.86c452b3.js    213.3 kB    69.9 kB
+
+  Total size:  531.8 kB
+  Gzipped size:  176.7 kB
+```
+
+By default, the build artifacts are generated in `dist/`, with the following directory structure:
+
+```
+dist
+├── html
+│   └── index
+├── modern.config.json
+├── route.json
+├── routes-manifest.json
+└── static
+    ├── css
+    └── js
+```
+
+> If you need to customize the directory of the build artifacts, please refer to [Output files](/guides/basic-features/output-files).

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

@@ -12,4 +12,4 @@ ready   Client compiled in 0.86 s
   > Network:  http://192.168.0.1:8080/
 ```
 
-Open `http://localhost:8000/` in your browser to see the page content.
+Open `http://localhost:8080/` in your browser to see the page content.

package/docs/en/components/enable-bff-caution.mdx

@@ -1,3 +1,3 @@
-:::caution
-Please use the [new command](/apis/app/commands#modern-new) in the root directory of the current project to enable BFF functionality first.
+:::tip
+Please refer to the [Enable BFF](/en/guides/advanced-features/bff/function.html#enable-bff) section in Basic Usage to enable BFF functionality first.
 :::

package/docs/en/components/enable-bff.mdx

@@ -1,22 +1,52 @@
-import { PackageManagerTabs } from '@theme';
+To enable BFF functionality in a Modern.js project, follow these steps to modify the code:
 
-1. Execute the `new` command:
+1. Install BFF plugin dependencies
 
-<PackageManagerTabs command="run new" />
+If the BFF plugin is not yet installed in your project, install it first:
 
-2. Follow the prompts to **enable BFF functionality**:
+```bash
+pnpm add @modern-js/plugin-bff
+```
+
+:::tip Version Consistency
+Make sure the version of `@modern-js/plugin-bff` 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-bff`:
 
 ```bash
-? Please select the operation you want to perform Enable optional features
-? Please select the feature to enable Enable "BFF"
+# Check the current version of @modern-js/app-tools
+pnpm list @modern-js/app-tools
+
+# Install the same version of @modern-js/plugin-bff
+pnpm add @modern-js/plugin-bff@<version>
 ```
 
-3. Depending on the chosen runtime framework, add the following code to `modern.config.[tj]s`:
+:::
+
+2. Configure modern.config.ts
+
+Import and add the BFF plugin in the `modern.config.[tj]s` file:
 
 ```ts title="modern.config.ts"
+import { defineConfig, appTools } from '@modern-js/app-tools';
 import { bffPlugin } from '@modern-js/plugin-bff';
 
 export default defineConfig({
-  plugins: [bffPlugin()],
+  plugins: [appTools(), bffPlugin()],
 });
 ```
+
+3. Configure TypeScript alias
+
+To correctly recognize the `@api` alias in TypeScript, it is recommended to add path mapping in `tsconfig.json`:
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "paths": {
+      ..., // other paths,
+      "@api/*": ["./api/lambda/*"]
+    }
+  }
+}
+```

package/docs/en/components/enable-ssg.mdx

@@ -0,0 +1,48 @@
+To enable SSG functionality in a Modern.js project, follow these steps to modify the code:
+
+1. Install SSG plugin dependencies
+
+If the SSG plugin is not yet installed in your project, install it first:
+
+```bash
+pnpm add @modern-js/plugin-ssg
+```
+
+:::tip Version Consistency
+Make sure the version of `@modern-js/plugin-ssg` 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-ssg`:
+
+```bash
+# Check the current version of @modern-js/app-tools
+pnpm list @modern-js/app-tools
+
+# Install the same version of @modern-js/plugin-ssg
+pnpm add @modern-js/plugin-ssg@<version>
+```
+
+:::
+
+2. Configure modern.config.ts
+
+Import and add the SSG plugin in the `modern.config.[tj]s` file, and configure `output.ssg`:
+
+```ts title="modern.config.ts"
+import { defineConfig, appTools } from '@modern-js/app-tools';
+import { ssgPlugin } from '@modern-js/plugin-ssg';
+
+export default defineConfig({
+  plugins: [appTools(), ssgPlugin()],
+  output: {
+    ssg: true,
+  },
+});
+```
+
+:::info Scope of Application
+
+- Use `output.ssg` for single-entry apps.
+- Use `output.ssgByEntries` for multi-entry apps.
+- When only `output.ssg: true` is set and `output.ssgByEntries` is not configured, all routes under all entries will be treated as SSG routes.
+
+:::

package/docs/en/components/entry-scan-logic.mdx

@@ -0,0 +1,7 @@
+:::tip Entry scanning logic
+- If `src/` itself meets entry criteria → Single-entry application
+- If `src/` does not meet criteria → Scan subdirectories under `src/` → Multi-entry application
+- In single-entry applications, the default entry name is `index`
+
+:::
+

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/install-command.mdx

@@ -0,0 +1,9 @@
+```bash
+pnpm add @modern-js/plugin-i18n i18next react-i18next
+```
+
+:::info
+`i18next` and `react-i18next` are peer dependencies and need to be installed manually.
+
+:::
+

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