@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.8 → 3.2.0-ultramodern.81

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

@@ -4,16 +4,16 @@ sidebar_position: 1
 
 # Commands
 
-Modern.js has some built-in commands that can help you quickly start a development server, build production environment code, and more.
+UltraModern.js has some built-in commands that can help you quickly start a development server, build production environment code, and more.
 
-Through this chapter, you can learn about the built-in commands of Modern.js and how to use them.
+Through this chapter, you can learn about the built-in commands of UltraModern.js and how to use them.
 
-## modern dev
+## ultramodern dev
 
-The `modern dev` command is used to start a local development server and compile the source code in the development environment.
+The `ultramodern dev` command is used to start a local development server and compile the source code in the development environment.
 
 ```bash
-Usage: modern dev [options]
+Usage: ultramodern dev [options]
 
 Options:
   -e --entry <entry>    compiler by entry
@@ -23,10 +23,10 @@ Options:
   --api-only            only start API service
 ```
 
-After running `modern dev`, Modern.js will watch source file changes and apply hot module replacement.
+After running `ultramodern dev`, UltraModern.js will watch source file changes and apply hot module replacement.
 
 ```bash
-$ modern dev
+$ ultramodern dev
 
 info    Starting dev server...
 
@@ -38,10 +38,10 @@ info    Starting dev server...
 
 In multi-page (MPA) projects, the `--entry` option can be added to specify one or more pages to compile. In this way, only part of the code in the project will be compiled, and the dev startup speed will be faster.
 
-For example, execute `modern dev --entry`, the entry selector will be displayed in the command line interface:
+For example, execute `ultramodern dev --entry`, the entry selector will be displayed in the command line interface:
 
 ```text
-$ modern dev --entry
+$ ultramodern dev --entry
 
 ? Please select the entry that needs to be built
 ❯ ◯ foo
@@ -57,22 +57,22 @@ You can also specify the page name through parameters after `--entry`, and the n
 
 ```bash
 # Compile foo page
-modern dev --entry foo
+ultramodern dev --entry foo
 
 # Compile foo and bar pages
-modern dev --entry foo,bar
+ultramodern dev --entry foo,bar
 ```
 
-## modern start
+## ultramodern start
 
-`modern start` is an alias of `modern dev` command, the usage of the two are exactly the same.
+`ultramodern start` is an alias of `ultramodern dev` command, the usage of the two are exactly the same.
 
-## modern build
+## ultramodern build
 
-The `modern build` command will build production-ready artifacts in the `dist/` directory by default. You can specify the output directory by modifying the configuration [`output.distPath`](/configure/app/output/dist-path).
+The `ultramodern build` command will build production-ready artifacts in the `dist/` directory by default. You can specify the output directory by modifying the configuration [`output.distPath`](/configure/app/output/dist-path).
 
 ```bash
-Usage: modern build [options]
+Usage: ultramodern build [options]
 
 Options:
   -c --config <config>  specify the configuration file, which can be a relative or absolute path
@@ -80,14 +80,14 @@ Options:
   -w --watch            turn on watch mode, watch for changes and rebuild
 ```
 
-## modern new
+## ultramodern new
 
-The `modern new` command is used to enable features in an existing project.
+The `ultramodern new` command is used to enable features in an existing project.
 
 For example, add application entry, enable some optional features such as BFF, micro frontend, etc.
 
 ```bash
-Usage: modern new [options]
+Usage: ultramodern new [options]
 
 Options:
   --config-file <configFile>  specify the configuration file, which can be a relative or absolute path
@@ -104,7 +104,7 @@ Options:
 In the project, execute the `new` command to add entries as follows:
 
 ```text
-$ npx modern new
+$ npx ultramodern new
 ? Please select the operation you want: Create Element
 ? Please select the type of element to create: New "entry"
 ? Please fill in the entry name: entry
@@ -115,7 +115,7 @@ $ npx modern new
 In the project, execute the `new` command to enable features as follows:
 
 ```text
-$ npx modern new
+$ npx ultramodern new
 ? Please select the operation you want: Enable Features
 ? Please select the feature name: (Use arrow keys)
 ❯ Enable BFF
@@ -133,12 +133,12 @@ import ServeCommand from '@site-docs-en/components/serve-command';
 
 <ServeCommand />
 
-## modern upgrade
+## ultramodern upgrade
 
-Execute the command `npx modern upgrade` in the project, by default, dependencies in the `package.json` are updated to the latest version.
+Execute the command `npx ultramodern upgrade` in the project, by default, dependencies in the `package.json` are updated to the latest version.
 
 ```bash
-Usage: modern upgrade [options]
+Usage: ultramodern upgrade [options]
 
 Options:
   --config <config> specify the configuration file, which can be a relative or absolute path
@@ -148,12 +148,12 @@ Options:
   -h, --help             show command help
 ```
 
-## modern inspect
+## ultramodern inspect
 
-The `modern inspect` command is used to view the Modern.js config, [Rsbuild config](https://v2.rsbuild.rs/config/index) and Rspack config of the project.
+The `ultramodern inspect` command is used to view the UltraModern.js config, [Rsbuild config](https://v2.rsbuild.rs/config/index) and Rspack config of the project.
 
 ```bash
-Usage: modern inspect [options]
+Usage: ultramodern inspect [options]
 
 Options:
   --env <env>           view the configuration in the target environment (default: "development")
@@ -163,14 +163,14 @@ Options:
   -h, --help            show command help
 ```
 
-After executing the command `npx modern inspect` in the project root directory, the following files will be generated in the `dist` directory of the project:
+After executing the command `npx ultramodern inspect` in the project root directory, the following files will be generated in the `dist` directory of the project:
 
 - `modern.js.config.mjs`:The Modern.js configuration currently used.
 - `rsbuild.config.mjs`: The Rsbuild config to use at build time.
 - `rspack.config.web.mjs`: The Rspack config used by to use at build time.
 
 ```bash
-➜ npx modern inspect
+➜ npx ultramodern inspect
 
 Inspect config succeed, open following files to view the content:
 
@@ -184,7 +184,7 @@ Inspect config succeed, open following files to view the content:
 By default, the inspect command will output the development configs, you can use the `--env production` option to output the production configs:
 
 ```bash
-modern inspect --env production
+ultramodern inspect --env production
 ```
 
 ### Verbose content
@@ -192,7 +192,7 @@ modern inspect --env production
 By default, the inspect command will omit the function content in the config object, you can use the `--verbose` option to output the full content of the function:
 
 ```bash
-modern inspect --verbose
+ultramodern inspect --verbose
 ```
 
 ### SSR Configuration
@@ -200,7 +200,7 @@ modern inspect --verbose
 If the project has enabled SSR, an additional `rspack.config.node.mjs` file will be generated in the `dist/`, corresponding to the Rspack configuration at SSR build time.
 
 ```bash
-➜ npx modern inspect
+➜ npx ultramodern inspect
 
 Inspect config succeed, open following files to view the content:
 

package/docs/en/community/blog/2022-0708-updates.md

@@ -17,7 +17,7 @@ Modern.js 7 ~ 8 月的最新版本为 v1.17.0，本双月的主要更新有：
 
 Modern.js 框架和相关插件完成对 React 18 的适配。现在，只需要将项目中的 `react`、`react-dom` 两个包的版本，升级到最新的 React 18 大版本，就可以使用 React 18 的新功能。
 
-注意，使用 `@modern-js/create` 命令默认创建的项目，安装的依赖 `react`、`react-dom` 的版本仍然为 17，如果希望使用 React 18，请手动升级这两个包的版本。
+注意，使用 `@bleedingdev/modern-js-create` 命令默认创建的项目，安装的依赖 `react`、`react-dom` 的版本仍然为 17，如果希望使用 React 18，请手动升级这两个包的版本。
 
 另外，SSR 流式渲染功能，目前尚在开发中，暂不支持。
 

package/docs/en/community/blog/2022-0910-updates.md

@@ -15,7 +15,7 @@ Modern.js 9 ~ 10 月的最新版本为 v1.21.0，本双月的主要更新有：
 
 Modern.js 框架完成了对 pnpm v7 的变更适配。
 
-使用 `npx @modern-js/create@modern-1` 创建项目时会根据用户当前环境的 pnpm 版本进行安装依赖操作，并且在初始化项目中会在 `.npmrc` 中添加
+使用 `pnpm dlx @bleedingdev/modern-js-create` 创建项目时会根据用户当前环境的 pnpm 版本进行安装依赖操作，并且在初始化项目中会在 `.npmrc` 中添加
 `strict-peer-dependencies=false` 配置，避免安装时由于 `peerDependencies` 缺失导致安装依赖失败问题。
 同时适配 `release`、`deploy` 命令对 pnpm v7 的支持。
 
@@ -67,7 +67,7 @@ pnpm run command --options
 
 - husky 升级至 v8
 
-使用 `npx @modern-js/create@modern-1` 创建项目时，husky 会默认安装 v8 版本，并移除 `package.json` 中 husky 的配置，使用 `.husky` 文件夹的形式管理 husky 配置。
+使用 `pnpm dlx @bleedingdev/modern-js-create` 创建项目时，husky 会默认安装 v8 版本，并移除 `package.json` 中 husky 的配置，使用 `.husky` 文件夹的形式管理 husky 配置。
 
 在初次安装依赖时需要执行 `npx husky install` 进行 husky 初始化，默认项目会在 prepare 命令中完成，如果 husky 配置未生效，可通过手动执行完成 husky 配置。
 

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

@@ -86,20 +86,20 @@ title: Modern.js v2 发布
 
 大家对 Modern.js 框架的第一印象可能是「一个大而全的框架」，但事实上，为了避免变得臃肿，**Modern.js 采取了渐进式设计**，将所有功能建立在灵活的插件系统之上，因此具备按需启用和可插拔的能力。
 
-Modern.js 期望能支持不同规模的项目研发，考虑到中大型项目和小型项目对功能的诉求存在差异，**Modern.js 的大多数功能都是按需启用的**。在创建项目时，Modern.js 默认只安装核心模块，使 npm 依赖保持轻量；当需要用到额外功能时，你可以通过 modern new 命令一键开启，并自动安装相关依赖。
+Modern.js 期望能支持不同规模的项目研发，考虑到中大型项目和小型项目对功能的诉求存在差异，**Modern.js 的大多数功能都是按需启用的**。在创建项目时，Modern.js 默认只安装核心模块，使 npm 依赖保持轻量；当需要用到额外功能时，你可以通过 ultramodern new 命令一键开启，并自动安装相关依赖。
 
-![modern new 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new-code.png)
+![ultramodern new 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new-code.png)
 
-<div style={{ textAlign: 'center', fontStyle: 'italic' }}>modern new 命令</div>
+<div style={{ textAlign: 'center', fontStyle: 'italic' }}>ultramodern new 命令</div>
 
 比如：
 
 - 对于基础的开发场景，项目中只需安装 Modern.js 的 CLI 工具 `@modern-js/app-tools`，即具备了开发调试、生产构建的能力。
-- 当你需要在应用中增加一些 BFF 接口时，可以执行 modern new 命令来启用 BFF 功能。启用后，Modern.js 会自动安装所需的 BFF 插件，以及某个 Node.js 框架对应的插件（如 Koa / Express）：
+- 当你需要在应用中增加一些 BFF 接口时，可以执行 ultramodern new 命令来启用 BFF 功能。启用后，Modern.js 会自动安装所需的 BFF 插件，以及某个 Node.js 框架对应的插件（如 Koa / Express）：
 
 ![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/bff-plugins.png)
 
-目前，你可以通过 `modern new` 命令来按需开启以下功能，未来我们也会将更多功能加入到 `new` 命令中，使其能够被便捷地集成。
+目前，你可以通过 `ultramodern new` 命令来按需开启以下功能，未来我们也会将更多功能加入到 `new` 命令中，使其能够被便捷地集成。
 
 ![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new.png)
 

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

@@ -339,7 +339,7 @@ For more on config-based routing, see the docs: [Config-Based Routing](/guides/b
 
 #### Route Debugging
 
-Run the `npx modern routes` command to generate a complete route structure analysis report in the `dist/routes-inspect.json` file.
+Run the `npx ultramodern routes` command to generate a complete route structure analysis report in the `dist/routes-inspect.json` file.
 
 The report displays each route's path, component file, data loader, error boundary, loading component, and other details, helping developers quickly understand the project's route configuration and troubleshoot routing issues. The structured JSON format is also easy for AI agents to understand and analyze, improving the efficiency of AI-assisted development.
 

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

@@ -39,8 +39,7 @@ nvm use 22
 ### Install pnpm
 
 ```sh
-# Enable pnpm with corepack, only available on Node.js >= `v14.19.0`
-corepack enable
+mise install
 ```
 
 ### Install Dependencies
@@ -125,7 +124,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 [Rstest](https://rstest.rs/).
+Modern.js uses [Rstest](https://rstest.rs/) for unit tests across the repository. You can add test cases in the `<PACKAGE_DIR>/tests` folder, using Rstest syntax.
 
 ### Run Unit Tests
 

package/docs/en/community/releases.mdx

@@ -24,8 +24,8 @@ Modern.js follows the [Semantic Versioning](https://semver.org) specification.
 
 ## Version Upgrade
 
-When you need to upgrade the Modern.js version in your project, you can use the `modern upgrade` command, refer to [Upgrade](/guides/get-started/upgrade).
+When you need to upgrade the Modern.js version in your project, you can use the `ultramodern upgrade` command, refer to [Upgrade](/guides/get-started/upgrade).
 
 ```bash
-npx modern upgrade
+npx ultramodern upgrade
 ```

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

@@ -3,7 +3,7 @@ To build the production artifacts of the project, run `pnpm run build` in the pr
 ```bash
 $ pnpm run build
 
-> modern build
+> ultramodern build
 
   Modern.js Framework
 

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

@@ -2,7 +2,7 @@ Run `pnpm run dev` in the project to start the project:
 
 ```bash
 $ pnpm run dev
-> modern dev
+> ultramodern dev
 
   Modern.js Framework
 

package/docs/en/components/deploy-command.mdx

@@ -1,9 +1,9 @@
-## modern deploy
+## ultramodern deploy
 
-The `modern deploy` command is used to generate artifacts required for the deployment platform.
+The `ultramodern deploy` command is used to generate artifacts required for the deployment platform.
 
 ```bash
-Usage: modern deploy [options]
+Usage: ultramodern deploy [options]
 
 Options:
   -c --config <config>  Specify configuration file path, either relative or absolute

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

@@ -1,64 +1,48 @@
-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`.
+UltraModern.js provides the BleedingDev create package to create projects. It does not require global installation and can be run on-demand using `pnpm dlx`.
 
-You can create a project in an existing empty directory:
+You can initialize the empty directory you are already in:
 
 ```bash
 mkdir myapp && cd myapp
-npx @modern-js/create@latest
+pnpm dlx @bleedingdev/modern-js-create .
 ```
 
 You can also create a project directly in a new directory:
 
 ```bash
-npx @modern-js/create@latest myapp
-```
-
-To initialize a TanStack Router template:
-
-```bash
-npx @modern-js/create@latest myapp --router tanstack
-```
-
-To initialize with Tailwind CSS v4 scaffold:
-
-```bash
-npx @modern-js/create@latest myapp --tailwind
+pnpm dlx @bleedingdev/modern-js-create myapp
 ```
 
-To initialize TanStack Router with Tailwind CSS v4:
+TanStack Router is scaffolded by default. To force React Router compatibility:
 
 ```bash
-npx @modern-js/create@latest myapp --router tanstack --tailwind
+pnpm dlx @bleedingdev/modern-js-create myapp --router react-router
 ```
 
-To initialize BFF scaffold with the current default runtime:
+Tailwind CSS v4 is scaffolded by default. To opt out:
 
 ```bash
-npx @modern-js/create@latest myapp --bff
+pnpm dlx @bleedingdev/modern-js-create myapp --no-tailwind
 ```
 
-To initialize BFF scaffold with Effect HttpApi runtime:
-
-```bash
-npx @modern-js/create@latest myapp --bff-runtime effect
-```
+Effect HttpApi BFF is scaffolded by default.
 
 To initialize BFF scaffold with Hono runtime:
 
 ```bash
-npx @modern-js/create@latest myapp --bff-runtime hono
+pnpm dlx @bleedingdev/modern-js-create myapp --bff-runtime hono
 ```
 
 To initialize with workspace protocol dependencies (for local monorepo testing of unreleased Modern.js packages):
 
 ```bash
-npx @modern-js/create@latest myapp --router tanstack --bff-runtime effect --workspace
+pnpm dlx @bleedingdev/modern-js-create myapp --workspace
 ```
 
-`@modern-js/create` will directly create the application without providing an interactive Q & A interface:
+The BleedingDev create package will directly create the application without providing an interactive Q & A interface:
 
 ```bash
-🚀 Welcome to Modern.js
+🚀 Welcome to UltraModern.js
 
 📦 Creating project "myapp"...
 
@@ -101,19 +85,37 @@ Now, the project structure is as follows:
 └── tsconfig.json
 ```
 
-When `--tailwind` is enabled, `postcss.config.mjs` and `tailwind.config.ts` are generated in the project root.
+Tailwind CSS v4 is generated by default; pass `--no-tailwind` to omit `postcss.config.mjs`, `tailwind.config.ts`, and the Tailwind import.
 
-When `--bff` or `--bff-runtime effect` is enabled, `modern.config.ts` enables `@modern-js/plugin-bff`, generates `api/effect/index.ts` + `shared/effect/api.ts`, and sets `bff.runtimeFramework` to `effect`.
+By default, `modern.config.ts` enables `@modern-js/plugin-bff`, generates `api/effect/index.ts` + `shared/effect/api.ts`, and sets `bff.runtimeFramework` to `effect`.
 When `--bff-runtime hono` is enabled, `modern.config.ts` enables `@modern-js/plugin-bff`, generates `api/lambda/hello.ts`, and sets `bff.runtimeFramework` to `hono`.
 When `--workspace` is enabled, `@modern-js/*` dependencies use `workspace:*` versions for local monorepo linkage.
 
-If you want the public UltraModern.js SuperApp path, use the BleedingDev create
-package. It defaults to the canonical Effect + TanStack + SSR + Micro Verticals
-workspace and published BleedingDev package aliases:
+It creates a simple production-ready UltraModern app by default and installs
+the published BleedingDev package aliases:
 
 ```bash
 pnpm dlx @bleedingdev/modern-js-create myapp
 ```
 
-The lower-level `--ultramodern-*` flags are reserved for release engineering
-and local package-source testing.
+Create a SuperApp workspace only when you need independently owned verticals:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
+```
+
+From a generated SuperApp workspace, add a business MicroVertical in place:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical
+```
+
+The `--vertical` command mutates the current workspace: it adds the vertical
+package and wires topology, ownership metadata, shell Module Federation,
+development overlays, package dependencies, generated contracts, route-owned
+i18n, CSS isolation, and the Effect BFF/client surface.
+
+The lower-level `--ultramodern-package-*` flags are reserved for release
+engineering and local package-source testing. BleedingDev packages are published
+through GitHub Actions trusted publishing; do not publish them manually from a
+developer machine.

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

@@ -1,5 +1,5 @@
 ```bash
-$ npx @modern-js/create@latest myapp
+$ pnpm dlx @bleedingdev/modern-js-create myapp
 ? Please select the programming language: TS
 ? Please select the package manager: pnpm
 ```

package/docs/en/components/prerequisites.mdx

@@ -9,8 +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
-corepack enable pnpm
-corepack prepare pnpm@11.1.2 --activate
+mise use pnpm@11.4.0
 ```
 
 :::note

package/docs/en/components/serve-command.mdx

@@ -1,9 +1,9 @@
-## modern serve
+## ultramodern serve
 
-The `modern serve` command is used to start a Modern.js project in the production environment. It can also be used to preview the artifacts built for the production environment locally. Please note that you need to execute the [`build`](/apis/app/commands#modern-build) command beforehand to generate the corresponding artifacts.
+The `ultramodern serve` command is used to start an UltraModern.js project in the production environment. It can also be used to preview the artifacts built for the production environment locally. Please note that you need to execute the [`build`](/apis/app/commands#ultramodern-build) command beforehand to generate the corresponding artifacts.
 
 ```bash
-Usage: modern serve [options]
+Usage: ultramodern serve [options]
 
 Options:
   -c --config <config>  specify the configuration file, which can be a relative or absolute path

package/docs/en/configure/app/bff/runtime-framework.mdx

@@ -25,4 +25,4 @@ export default defineConfig({
 - Set to `'hono'` to run BFF only from file-convention handlers under `api/lambda/**`.
 
 There is no implicit fallback between runtimes. Choose one runtime mode per app.
-If you want the public UltraModern preset that prefers the Effect lane, configure it explicitly in your app or scaffold with the create template's Effect path.
+Generated UltraModern apps use the Effect lane by default; set `runtimeFramework: 'hono'` only for the compatibility runtime.

package/docs/en/configure/app/usage.mdx

@@ -86,8 +86,8 @@ export default defineConfig(({ env, command }) => ({
 This function accepts the following parameters:
 
 - `env`: Corresponds to the value of `process.env.NODE_ENV`.
-  - When running `modern dev`, the value of `env` is `development`.
-  - When running `modern build` or `modern serve`, the value of `env` is `production`.
+  - When running `ultramodern dev`, the value of `env` is `development`.
+  - When running `ultramodern build` or `ultramodern serve`, the value of `env` is `production`.
 - `command`: Corresponds to the current command being run, such as `dev`, `build`, or `serve`.
 
 #### Exporting Asynchronous Functions
@@ -117,8 +117,8 @@ For example, if you need to use the `modern.prod.config.js` file when executing
 ```json title="package.json"
 {
   "scripts": {
-    "dev": "modern dev",
-    "build": "modern build --config modern.prod.config.js"
+    "dev": "ultramodern dev",
+    "build": "ultramodern build --config modern.prod.config.js"
   }
 }
 ```
@@ -126,7 +126,7 @@ For example, if you need to use the `modern.prod.config.js` file when executing
 You can also abbreviate the `--config` option as `-c`:
 
 ```bash
-$ modern build -c modern.prod.config.js
+$ ultramodern build -c modern.prod.config.js
 ```
 
 ### Configuring in package.json (Not Recommended)
@@ -187,7 +187,7 @@ The configuration in the `modern.config.local.ts` file will be deeply merged wit
 
 When using `modern.config.local.ts`, please note the following:
 
-- The `modern.config.local.ts` file will only be loaded when executing the `modern dev` commands and will not be loaded during `modern build`.
+- The `modern.config.local.ts` file will only be loaded when executing the `ultramodern dev` commands and will not be loaded during `ultramodern build`.
 - The priority of the `modern.config.local.ts` file is higher than both `modern.config.ts` and the `modernConfig` field in `package.json`.
 - Since `modern.config.local.ts` is only used for local debugging, it is not recommended to commit it to the code repository. Ensure that the project's `.gitignore` file includes `modern.config.local.ts` and similar files.
 

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

@@ -15,10 +15,13 @@ title: API Reference
 | `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 treats localised URL paths as enabled. Route generation still requires every localisable path to define every configured language unless you set `localisedUrls: false`.
+
 ### Basic Usage
 
 ```tsx
@@ -91,7 +94,7 @@ A route link component with a 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 | Inherited from the `Link` component in `@modern-js/runtime/router` |
+| Other Link props | - | No | Passed to the active router link when a router is available |
 
 ### Usage
 

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

@@ -49,6 +49,7 @@ export default defineConfig({
 | `languages` | `string[]` | `[]` | Supported language list |
 | `fallbackLanguage` | `string` | `''` | Fallback language when detection fails |
 | `localePathRedirect` | `boolean` | `false` | Handles URL locale prefix recognition, redirects, and switching. See [Routing Integration](./routing.md#enable-locale-path-prefixes) |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | `true` when `localePathRedirect` is enabled | Localised route path map. Every localisable route must define every configured language. Set `false` to keep locale prefixes without translating path segments. |
 | `i18nextDetector` | `boolean` | `false` | Enables the i18next detector (Cookie / Header, etc.) |
 | `detection` | `LanguageDetectorOptions` | - | Detailed i18next detector configuration. See [Locale Detection](./locale-detection.md) |
 | `ignoreRedirectRoutes` | `string[] \| Function` | - | Routes that skip redirects. See [Locale Detection](./locale-detection.md#ignoreredirectroutes) |

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

@@ -113,7 +113,7 @@ i18nPlugin({
 
 ## ignoreRedirectRoutes
 
-Specify which paths should skip locale path redirects. This is useful for API routes, static assets, and other paths that do not need a locale prefix.
+Specify which additional paths should skip locale path redirects. Modern.js automatically skips server API routes and BFF prefixes, including configured `bff.prefix` values. Use `ignoreRedirectRoutes` for non-API application paths that also do not need a locale prefix.
 
 **Syntax 1: string array** (supports exact match and prefix match)
 

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

@@ -32,7 +32,48 @@ i18nPlugin({
 | `/en/about` | Visits normally, language is `en` |
 | `/zh/about` | Visits normally, language is `zh` |
 
-Some paths, such as API routes and static assets, do not need locale prefixes. Use `ignoreRedirectRoutes` to skip redirects. See [Locale Detection -> ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes).
+API and BFF prefixes are skipped automatically, so server API routes do not need locale prefixes or `localisedUrls` entries. For additional application paths that should not redirect, use `ignoreRedirectRoutes`. See [Locale Detection -> ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes).
+
+## Localised URL Paths
+
+When `localePathRedirect` is enabled, `localisedUrls` is enabled by default. This means every localisable route path must define a URL for every configured language. If you add a new language to `languages`, Modern.js will fail route generation until each localised URL entry includes that language too.
+
+`localisedUrls` applies to file-system routes generated for both React Router and TanStack Router projects. Do not configure localised URL entries for API routes, BFF prefixes, or configured `bff.prefix` values; those paths are excluded from locale redirects automatically.
+
+```ts
+// modern.config.ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['en', 'cs'],
+    fallbackLanguage: 'en',
+    localisedUrls: {
+      '/terms-of-service': {
+        en: '/terms-of-service',
+        cs: '/podminky-pouzivani',
+      },
+      '/products': {
+        en: '/products',
+        cs: '/produkty',
+      },
+      '/products/:slug': {
+        en: '/products/:slug',
+        cs: '/produkty/:slug',
+      },
+    },
+  },
+});
+```
+
+**Result:**
+
+| Visited path | Result |
+| --- | --- |
+| `/terms-of-service` | Redirects to `/en/terms-of-service` |
+| `/cs/terms-of-service` | Redirects to `/cs/podminky-pouzivani` |
+| `/cs/podminky-pouzivani` | Visits normally, language is `cs` |
+
+Set `localisedUrls: false` only when you want locale prefixes without translated path segments.
 
 ## Route Configuration
 
@@ -131,4 +172,4 @@ function Navigation() {
 <I18nLink to="/en/about">About</I18nLink>
 ```
 
-`I18nLink` extends the `Link` component from `@modern-js/runtime/router` and supports all standard Link props such as `replace`, `state`, and `className`. For the full Props type, see [API Reference](./api.md#i18nlink-component).
+`I18nLink` uses the active Modern.js router. In React Router projects it renders the React Router `Link`; in TanStack Router projects it navigates through TanStack Router. For the full Props type, see [API Reference](./api.md#i18nlink-component).

package/docs/en/guides/basic-features/debug/using-storybook.mdx

@@ -55,7 +55,7 @@ Add the following scripts to `package.json` to start the BFF server and Storyboo
 ```json
 {
   "scripts": {
-    "dev:api": "modern dev --api-only",
+    "dev:api": "ultramodern dev --api-only",
     "storybook": "BFF_PROXY=1 storybook dev -p 6006 --no-open",
   }
 }