@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.99 → 3.4.0-ultramodern.1

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

@@ -105,7 +105,7 @@ const layer = HttpApiBuilder.layer(bffEffectApi).pipe(
 export default defineEffectBff({ api: bffEffectApi, layer });
 ```
 
-Call Effect endpoints from the browser via `@api/effect/index`:
+Call Effect endpoints from browser code via `@api/effect/index`:
 
 ```ts title="src/routes/page.tsx"
 import effectBff from '@api/effect/index';
@@ -113,6 +113,8 @@ import effectBff from '@api/effect/index';
 const response = await effectBff.client.hello.ping({});
 ```
 
+The `effectBff.client.*` surface is materialized by the BFF loader for `@api/effect/*` imports. Do not import `api/effect/index` directly and expect `client` to run in server code, scripts, or tests; direct entry imports expose the server runtime definition, and `client` is only a typed placeholder there.
+
 import Hono from '@site-docs-en/components/hono';
 
 <Hono />

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

@@ -20,7 +20,7 @@ title: API Reference
 | `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`.
+When `localePathRedirect` is enabled and `localisedUrls` is omitted, Modern.js keeps prefix-only paths such as `/en/about`. Translated path segments are enabled only by a non-empty `localisedUrls` map. Route generation validates every localisable path and every configured language only while that map is enabled.
 
 ### Basic Usage
 

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

@@ -49,7 +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. |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | Prefix-only behavior | Localised route path map. Only a non-empty map enables translated path segments; omitted, `true`, `false`, and `{}` 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 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.
+Specify which additional paths should skip locale path redirects. Modern.js automatically skips server API routes, the default `/api` BFF prefix when BFF is configured, and custom `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,11 +32,13 @@ i18nPlugin({
 | `/en/about` | Visits normally, language is `en` |
 | `/zh/about` | Visits normally, language is `zh` |
 
-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).
+API and BFF prefixes are skipped automatically, including server API routes, the default `/api` BFF prefix when BFF is configured, and custom `bff.prefix` values. Those 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.
+`localePathRedirect` only adds and reads locale prefixes by default, for example `/en/about`. Translated path segments are opt-in: `localisedUrls` is enabled only when you provide a non-empty map. Omitting `localisedUrls`, setting it to `true`, setting it to `false`, or passing an empty object keeps prefix-only behavior.
+
+When a non-empty `localisedUrls` map is configured, 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.
 
@@ -73,7 +75,7 @@ i18nPlugin({
 | `/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.
+Set `localisedUrls: false` as the escape hatch when a preset, shared config, or generated metadata would otherwise provide a map but this entry should keep locale prefixes without translated path segments.
 
 ## Route Configuration
 

package/docs/en/guides/advanced-features/web-server.mdx

@@ -48,6 +48,18 @@ export default defineServerConfig({
 
 After creating the file, you can write custom logic in this file.
 
+3. Include `server` directory in `tsconfig.json`
+
+```json5
+{
+  // ...
+  "include": [
+    // ...
+    "server"
+  ]
+}
+```
+
 ## Capabilities of the Custom Web Server
 
 Modern.js's Web Server is based on Hono, and in the latest version of the Custom Web Server, we expose Hono's middleware capabilities, you can refer to [Hono API](https://hono.dev/docs/api/context) for more usage.

package/docs/en/guides/basic-features/debug/rsdoctor.mdx

@@ -2,14 +2,13 @@
 
 Rsdoctor is a Rspack build analysis tool. In Modern.js, we recommend using Rsdoctor to diagnose and analyze the build process and build outputs.
 
-Modern.js enables Rsdoctor by default for production builds.
+Modern.js does not enable Rsdoctor by default. Configure `performance.rsdoctor` when you want to run Rsdoctor for a build.
 
 ## Execute Build
 
 ```ts title="modern.config.ts"
 export default defineConfig({
   performance: {
-    // Enabled by default in production build.
     rsdoctor: true,
   },
 });
@@ -21,7 +20,7 @@ npm run build
 
 ## Disable Rsdoctor
 
-If you want to disable Rsdoctor:
+If you want to disable Rsdoctor after enabling it in shared config:
 
 ```ts title="modern.config.ts"
 export default defineConfig({

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": "ultramodern dev --api-only",
+    "dev:api": "modern dev --api-only",
     "storybook": "BFF_PROXY=1 storybook dev -p 6006 --no-open",
   }
 }

package/docs/en/guides/basic-features/deploy.mdx

@@ -15,12 +15,12 @@ Currently, Modern.js only supports running in a Node.js environment. Support for
 
 ## Build Deployment Products
 
-Running the `ultramodern deploy` command will automatically produce deployment products. This process includes optimizing Bundler build products and their dependencies, detecting the current deployment platform, and automatically generating deployment products that can run on that platform.
+Running the `modern deploy` command will automatically produce deployment products. This process includes optimizing Bundler build products and their dependencies, detecting the current deployment platform, and automatically generating deployment products that can run on that platform.
 
-If you want to generate and test the output locally for a specific deployment platform, you can specify the platform by setting the environment variable: `ultramodern deploy`:
+If you want to generate and test the output locally for a specific deployment platform, you can specify the platform by setting the environment variable: `modern deploy`:
 
 ```bash
-MODERNJS_DEPLOY=netlify npx ultramodern deploy
+MODERNJS_DEPLOY=netlify npx modern deploy
 ```
 
 :::info
@@ -36,10 +36,10 @@ By default, Modern.js outputs builds that can be run in a Node.js environment wh
 Use the following command to build the project:
 
 ```bash
-npx ultramodern deploy
+npx modern deploy
 ```
 
-When running the `ultramodern deploy` command, UltraModern.js will generate runnable products and output the following content in terminal:
+When running the `modern deploy` command, UltraModern.js will generate runnable products and output the following content in terminal:
 
 ```bash
 Static directory: `.output/static`
@@ -67,7 +67,7 @@ Assume that the name in the `package.json` of the current project is `app`. Taki
 {
   "scripts": {
     "build:packages": "pnpm --filter 'app^...' run build",
-    "deploy": "pnpm run build:packages && ultramodern deploy"
+    "deploy": "pnpm run build:packages && modern deploy"
   }
 }
 ```
@@ -78,7 +78,7 @@ If you use Rush as your Monorepo management tool, you can add the following comm
 {
   "scripts": {
     "build:packages": "rush rebuild --to-except app",
-    "deploy": "rushx build:packages && ultramodern deploy"
+    "deploy": "rushx build:packages && modern deploy"
   }
 }
 ```
@@ -108,7 +108,7 @@ Add the following content to `netlify.toml`:
 ```toml
 [build]
   publish = "dist"
-  command = "ultramodern deploy"
+  command = "modern deploy"
 ```
 
 :::info
@@ -125,7 +125,7 @@ Full-stack projects refer to projects that use Custom Web Server, SSR or BFF. Th
 ```toml title="netlify.toml"
 [build]
   publish = "dist"
-  command = "ultramodern deploy"
+  command = "modern deploy"
 
 [functions]
   directory = ".netlify/functions"
@@ -173,7 +173,7 @@ Add the following script in `packages/app/package.json`, before executing the de
 {
   "scripts": {
     "build:packages": "pnpm --filter 'app^...' run build",
-    "deploy": "pnpm run build:packages && ultramodern deploy"
+    "deploy": "pnpm run build:packages && modern deploy"
   }
 }
 ```
@@ -213,7 +213,7 @@ Add the following content to `vercel.json`:
 
 ```json title="vercel.json"
 {
-  "buildCommand": "ultramodern deploy",
+  "buildCommand": "modern deploy",
   "outputDirectory": ".vercel/output"
 }
 ```
@@ -281,7 +281,7 @@ Add the following script to `packages/app/package.json` to run `build` command o
 {
   "scripts": {
     "build:packages": "pnpm --filter 'app^...' run build",
-    "deploy": "pnpm run build:packages && ultramodern deploy"
+    "deploy": "pnpm run build:packages && modern deploy"
   }
 }
 ```
@@ -326,7 +326,7 @@ For branch deployment, follow these steps:
 ```
 "scripts": {
   //...
-  "deploy:gh-pages": "MODERNJS_DEPLOY=ghPages ultramodern deploy && gh-pages -d .output"
+  "deploy:gh-pages": "MODERNJS_DEPLOY=ghPages modern deploy && gh-pages -d .output"
 }
 ```
 
@@ -334,7 +334,7 @@ For branch deployment, follow these steps:
 
 :::info
 
-1. Running `MODERNJS_DEPLOY=ghPages ultramodern deploy` will build the production output for GitHub in the .output directory.
+1. Running `MODERNJS_DEPLOY=ghPages modern deploy` will build the production output for GitHub in the .output directory.
 2. You can refer to the [project](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)
    :::
 

package/docs/en/guides/basic-features/env-vars.mdx

@@ -16,8 +16,8 @@ The current path prefix of the asset, which is a read-only environment variable.
 
 The current execution environment and is a **read-only** environment variable whose have different values under different execution commands:
 
-- `production`: Default value when running `ultramodern build` or `ultramodern serve`.
-- `development`: Default value when running `ultramodern dev`, also the default value in other cases.
+- `production`: Default value when running `modern build` or `modern serve`.
+- `development`: Default value when running `modern dev`, also the default value in other cases.
 
 ### MODERN_ENV
 

package/docs/en/guides/basic-features/render/_meta.json

@@ -1,10 +1 @@
-[
-  "overview",
-  "ssr",
-  "streaming-ssr",
-  "ssr-cache",
-  "ssg",
-  "rsc",
-  "tanstack-rsc",
-  "before-render"
-]
+["overview", "ssr", "streaming-ssr", "ssr-cache", "ssg", "rsc", "before-render"]

package/docs/en/guides/basic-features/render/overview.mdx

@@ -47,6 +47,5 @@ Modern.js supports combining multiple rendering modes:
 - [Server-Side Rendering (SSR)](/guides/basic-features/render/ssr)
 - [Streaming Server-Side Rendering (Streaming SSR)](/guides/basic-features/render/streaming-ssr)
 - [React Server Components (RSC)](/guides/basic-features/render/rsc)
-- [TanStack Router RSC](/guides/basic-features/render/tanstack-rsc)
 - [Static Site Generation (SSG)](/guides/basic-features/render/ssg)
 - [Rendering Cache](/guides/basic-features/render/ssr-cache)

package/docs/en/guides/basic-features/render/rsc.mdx

@@ -531,4 +531,3 @@ The project's bundle has introduced a non-19 React version, commonly seen in mon
 - [Data Cache](/guides/basic-features/data/data-cache)
 - [Server-Side Rendering (SSR)](/guides/basic-features/render/ssr)
 - [Streaming SSR](/guides/basic-features/render/streaming-ssr)
-- [TanStack Router RSC](/guides/basic-features/render/tanstack-rsc)

package/docs/en/guides/basic-features/routes/config-routes.mdx

@@ -271,7 +271,7 @@ Config routes can be used together with convention routes. You can merge routes
 
 :::info
 
-Current route structure can be viewed through the [`ultramodern routes`](#debugging-routes) command
+Current route structure can be viewed through the [`modern routes`](#debugging-routes) command
 
 :::
 
@@ -319,7 +319,7 @@ Since the final structure after route merging may not be intuitive, Modern.js pr
 
 ```bash
 # Generate route structure analysis report
-npx ultramodern routes
+npx modern routes
 ```
 
 This command will generate the final route structure in the `dist/routes-inspect.json` file, helping you understand the complete route information after merging.

package/docs/en/guides/basic-features/routes/routes.mdx

@@ -464,7 +464,7 @@ When defining a `loading.tsx`, if the route transitions from `/` to `/blog` or f
 
 ## Prefetching
 
-Most white screens during route transitions can be optimized by defining a `<Loading>` component. Modern.js also supports preloading static resources and data with the `prefetch` attribute on `<Link>` components.
+Most white screens during route transitions can be optimized by defining a `<Loading>` component. Modern.js also supports navigation warmup with the `prefetch` and `preload` attributes on `<Link>` components.
 
 For applications with higher performance requirements, prefetching can further enhance the user experience by reducing the time spent displaying the `<Loading>` component:
 
@@ -474,21 +474,36 @@ For applications with higher performance requirements, prefetching can further e
 
 :::tip
 
-Data preloading currently only preloads data returned by the [Data Loader](/guides/basic-features/data/data-fetch) in SSR projects.
+In SSR projects, same-origin route data returned by the [Data Loader](/guides/basic-features/data/data-fetch) is prefetched for matched routes with callable loaders. Set `handle.navigationWarmup.data` to `false` on a route when its loader data should not be requested before navigation.
 
 :::
 
-The `prefetch` attribute has three optional values:
+By default, same-origin links prefetch the route module and matching loader data when the `<Link>` renders. Modern.js skips these automatic warmups on Save-Data or slow network connections.
 
-- `none`: The default value. No prefetching, no additional behavior.
-- `intent`: This is the recommended value for most scenarios. When you hover over the Link, it will automatically start loading the corresponding chunk and the data defined in the Data Loader. If the mouse moves away, the loading is automatically canceled. In our tests, even quick clicks can reduce load time by approximately 200ms.
-- `render`: When the `<Link>` component is rendered, it begins loading the corresponding chunk and data defined in the Data Loader.
+The `prefetch` attribute has four optional values:
+
+- `render`: The default value. When the `<Link>` component is rendered, it begins warming the corresponding route module.
+- `intent`: When users focus, hover, or touch the link, it starts warming the corresponding route module. If the intent is canceled before warmup starts, the warmup is canceled.
+- `viewport`: When the `<Link>` component enters the viewport, it begins warming the corresponding route module.
+- `none`: Disables automatic prefetching. It also disables implicit preload unless an explicit `preload` value is provided.
+
+The `preload` attribute accepts the same timing values and defaults to the `prefetch` timing. Explicit `preload` values always win, and `preload={false}` disables preload behavior.
+
+To opt a route out of SSR data warmup:
+
+```ts title="routes/page.config.ts"
+export const handle = {
+  navigationWarmup: {
+    data: false,
+  },
+};
+```
 
 :::details Difference Between "render" and Not Using Route Splitting
 
-- `render` allows you to control the timing of route splitting, triggering only when the `<Link>` component enters the viewport. You can control the loading timing of the split by adjusting the rendering position of the `<Link>` component.
-- `render` loads static resources only during idle times, thus not occupying the loading time of critical modules.
-- Besides preloading route splits, `render` will also initiate data prefetching in SSR projects.
+- `render` allows you to control route-module warmup with the position of the `<Link>` component in the tree.
+- `viewport` lets you defer module warmup until the link is close to becoming actionable.
+- SSR data prefetching is enabled by default; use `handle.navigationWarmup.data = false` for routes whose loader data is not safe or useful to fetch before navigation.
 
 :::
 
@@ -513,5 +528,5 @@ If you encounter API usage issues, check the corresponding upstream docs:
 - TanStack Router docs for `@modern-js/plugin-tanstack/runtime`.
 
 :::note
-If you must directly use the React Router package's API (e.g., route behavior wrapped in a unified npm package), you can set [`source.alias`](/configure/app/source/alias) to point `react-router` and `react-router-dom` to the project's dependencies, avoiding the issue of two versions of React Router.
+If you must directly use the React Router package's API (e.g., route behavior wrapped in a unified npm package), you can set [`source.alias`](/configure/app/source/alias) to point `react-router` to the project's dependency, avoiding the issue of two React Router versions.
 :::

package/docs/en/guides/basic-features/testing/rstest.mdx

@@ -8,6 +8,7 @@ This guide explains how to integrate Rstest with Modern.js for web app testing.
 
 Install the base dependencies first:
 
+import { Prompt } from '@rspress/core/theme';
 import { PackageManagerTabs } from '@theme';
 
 <PackageManagerTabs command="add @rstest/core @modern-js/adapter-rstest -D" />
@@ -161,3 +162,31 @@ Execute the `test` command above to run your tests:
 If you need node mode tests for server-side logic such as `bff`, refer to the [Rstest documentation](https://rstest.rs) directly.
 
 Modern.js mainly targets web apps, so this guide focuses on web UI testing and browser mode.
+
+## Migrating from Existing Projects
+
+If your project already uses Jest or Vitest, refer to the official Rstest migration guides:
+
+- [Migrate from Jest to Rstest](https://rstest.rs/guide/migration/jest)
+- [Migrate from Vitest to Rstest](https://rstest.rs/guide/migration/vitest)
+
+We recommend installing the `migrate-to-rstest` skill first, then copying this prompt to your coding agent. It keeps the Modern.js `@modern-js/adapter-rstest` integration during migration:
+
+<Prompt
+  title="Migrate to Rstest"
+  description="Copy this prompt and send it to your coding agent."
+  prompt={`Migrate this Modern.js project from Jest or Vitest to Rstest.
+
+First install and use the migrate-to-rstest skill. If it is not installed, install it with:
+npx skills add rstackjs/agent-skills --skill migrate-to-rstest
+
+Follow the migrate-to-rstest skill instructions and the official Rstest migration guides:
+- Jest: https://rstest.rs/guide/migration/jest
+- Vitest: https://rstest.rs/guide/migration/vitest
+
+Modern.js-specific requirement:
+- Install and use @modern-js/adapter-rstest together with @rstest/core.
+- Create or update rstest.config.ts to import withModernConfig from @modern-js/adapter-rstest.
+- Reuse the Modern.js app configuration with extends: withModernConfig().
+- Do not replace this with a plain Rstest config unless the project explicitly does not need Modern.js config integration.`}
+/>

package/docs/en/guides/concept/server.mdx

@@ -26,10 +26,10 @@ Static asset files can be directly hosted by Modern.js' server, but it is highly
 
 Modern.js supports running built artifacts in any Node.js environment. Typically, the CI environment has already installed all application dependencies.
 
-You can run the [`ultramodern build`](/apis/app/commands#ultramodern-build) command to build the application and the [`ultramodern serve`](/apis/app/commands#ultramodern-serve) command to run the Web server, starting the UltraModern.js application.
+You can run the [`modern build`](/apis/app/commands#modern-build) command to build the application and the [`modern serve`](/apis/app/commands#modern-serve) command to run the Web server, starting the UltraModern.js application.
 
 ## Running in Production Environments
 
 When deploying to production, the artifact size should be as small as possible. The aforementioned method for running in CI environments keeps all artifacts from the original project. Therefore, it is not recommended to run the application using the above commands in a production environment.
 
-UltraModern.js offers a standalone deployment solution. When running the [`ultramodern deploy`](/apis/app/commands#ultramodern-deploy) command, the artifacts will include an entry file for running the Web server.
+UltraModern.js offers a standalone deployment solution. When running the [`modern deploy`](/apis/app/commands#modern-deploy) command, the artifacts will include an entry file for running the Web server.

package/docs/en/guides/get-started/quick-start.mdx

@@ -48,7 +48,7 @@ After running `pnpm run dev` again, you can find that the project has completed
 
 In a newly created project, the `@modern-js/app-tools` npm package is installed by default. It is the core package of the Modern.js framework and provides the following capabilities:
 
-- It offers commonly used CLI commands such as `ultramodern dev`, `ultramodern build`, and more.
+- It offers commonly used CLI commands such as `modern dev`, `modern build`, and more.
 - It integrates Rsbuild, providing build capabilities.
 - It integrates Modern.js Server, providing capabilities for development and production servers.