@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.100 → 3.5.0-ultramodern.102

package/docs/guides/get-started/glossary.md

@@ -0,0 +1,63 @@
+# Glossary
+
+## BFF
+
+BFF is short for "Backend For Frontend". It is an architecture pattern that involves creating a backend service for frontend applications.
+
+The BFF service acts as an intermediary between the frontend application and the server API, and can provide customized APIs for the frontend to use. This allows frontend developers to have more control over the data and functionality they need, without relying on the backend service to provide the corresponding capabilities.
+
+## Bundler
+
+Refers to module bundlers such as [Rspack](https://rspack.rs/).
+
+The main goal of bundlers is to bundle JavaScript, CSS and other files together, and the bundled files can be used in the browser, Node.js or other environments. When bundler processes the Web application, it builds a dependency graph and then combines every module into one or more bundles.
+
+## CSR
+
+CSR stands for "Client-Side Rendering". It means that the page is rendered in the browser using JavaScript, and logic such as data fetching, templates, and routing is completed on the client side rather than the server.
+
+In CSR, the server sends an empty HTML shell and some JavaScript scripts to the browser, and the browser fetching data from the server's API and renders dynamic content to the page.
+
+## Module Federation
+
+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.
+
+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.
+
+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.
+
+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).
+
+## Rsbuild
+
+[Rsbuild](https://v2.rsbuild.rs/) is an Rspack-based build tool for the web. The main goal of Rsbuild is to provide out-of-the-box build capabilities for Rspack users, allowing developers to start a web project with zero configuration.
+
+Rsbuild integrates high-performance Rust-based tools from the community, including Rspack and SWC, to provide first-class build speed and development experience.
+
+## Rspack
+
+[Rspack](https://rspack.rs/) is a high performance JavaScript bundler written in Rust. It offers strong compatibility with the webpack ecosystem, allowing for seamless replacement of webpack, and provides lightning fast build speeds.
+
+Compared to webpack, Rspack has significantly improved build performance, thanks not only to the language advantages brought by Rust, but also to its parallel architecture and incremental compilation features. Benchmarking has shown that Rspack can provide 5-10 times better compilation performance.
+
+## SSR
+
+SSR stands for "Server-Side Rendering". It means that the HTML of the web page is generated by the server and sent to the client, rather than sending only an empty HTML shell and relying on JavaScript to generate the page content.
+
+In traditional client-side rendering, the server sends an empty HTML shell and some JavaScript scripts to the client, and then fetching data from the server's API and fills the page with dynamic content. This leads to slow initial page loading times and is not conducive to user experience and SEO.
+
+With SSR, the server generates HTML that already contains dynamic content and sends it to the client. This makes the initial page loading faster and more SEO-friendly, as search engines can crawl the rendered page.
+
+## SSG
+
+SSG stands for "Static Site Generation". It means that web pages are pre-rendered as static HTML and served directly to the client, without the need for the server to generate HTML in real-time.
+
+In traditional SSR, the server generates HTML in real-time every time a user requests a page. With SSG, HTML can be generated in advance during the build process and hosted on a CDN or other static assets service.
+
+Compared to traditional SSR, SSG can provide faster loading speeds and less server-side overhead, as there is no need to maintain a server to generate HTML in real-time. However, SSG is not suitable for websites that require dynamic content, as the HTML is generated during the build process and does not support real-time updates.
+
+## SWC
+
+[SWC](https://SWC.rs/) (Speedy Web Compiler) is a transformer and minimizer for JavaScript and TypeScript based on `Rust`. SWC can provide the same abilities with Babel, and it's more than 10x faster than Babel.
+
+Modern.js has a out-of-box plugin for SWC, power your Web application with Polyfill and minification, we also port some common used Babel plugins to SWC.

package/docs/guides/get-started/{introduction.mdx → introduction.md}

@@ -1,8 +1,3 @@
----
-title: Introduction
-sidebar_position: 1
----
-
 # Introduction to Modern.js
 
 **Modern.js is a progressive web framework based on React**. At ByteDance, we use Modern.js to build upper-level frameworks that have supported the development of thousands of web applications.
@@ -42,4 +37,4 @@ Pelease refer to [Modern.js vs Remix](https://github.com/web-infra-dev/modern.js
 
 ## Next Step
 
-If you want to understand the compatibility-first differences between Modern.js v3 and UltraModern.js v3, read [UltraModern.js](/guides/get-started/ultramodern).
+If you want to understand the compatibility-first differences between Modern.js v3 and UltraModern.js v3, read [UltraModern.js](/guides/get-started/ultramodern.md).

package/docs/guides/get-started/quick-start.md

@@ -0,0 +1,269 @@
+# Quick Start
+
+## Environment
+
+### Node.js
+
+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:
+
+```bash
+node -v
+```
+
+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:
+
+```bash
+# Install the long-term support version of Node.js 22
+nvm install 22 --lts
+
+# Make the newly installed Node.js 22 as the default version
+nvm alias default 22
+
+# Switch to the newly installed Node.js 22
+nvm use 22
+```
+
+:::tip nvm and fnm
+Both nvm and fnm are Node.js version management tools. Relatively speaking, nvm is more mature and stable, while fnm is implemented using Rust, which provides better performance than 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.
+
+### pnpm
+
+It is recommended to use [pnpm](https://pnpm.io/installation) to manage dependencies:
+
+```bash
+mise use pnpm@11.17.0
+```
+
+:::note
+Modern.js also supports dependency management with `yarn` and `npm`.
+
+:::
+
+## Installation
+
+## Initialize
+
+UltraModern.js provides the BleedingDev create package to create SuperApp
+workspaces. It does not require global installation and can be run on-demand
+using `pnpm dlx`.
+
+The supported pnpm command is the scoped package specifier:
+`pnpm dlx @bleedingdev/modern-js-create <target>`. Do not shorten it to
+`pnpm dlx modern-js-create`; there is no unscoped package by that name.
+
+You can initialize the empty directory you are already in:
+
+```bash
+mkdir myapp && cd myapp
+pnpm dlx @bleedingdev/modern-js-create .
+```
+
+You can also create a project directly in a new directory:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app
+```
+
+To initialize with workspace protocol dependencies (for local monorepo testing of unreleased Modern.js packages):
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app --workspace
+```
+
+The BleedingDev create package will directly create the application without providing an interactive Q & A interface:
+
+```bash
+🚀 Welcome to UltraModern.js
+
+📦 Creating project "my-super-app"...
+
+✨ Project created successfully! 🎉
+
+📋 Next, you can run the following commands:
+
+📁 Enter the project directory:
+
+  cd my-super-app
+
+🔧 Initialize Git repository:
+
+  git init
+
+📥 Install project dependencies:
+
+  pnpm install
+
+⚡ Start the development server:
+
+  pnpm start
+```
+
+Now, the project structure is as follows:
+
+```
+.
+├── apps
+│   └── shell-super-app
+├── package.json
+├── packages
+│   ├── shared-contracts
+│   ├── shared-design-tokens
+│   └── shared-effect-client
+├── scripts
+├── topology
+└── verticals
+```
+
+The default workspace starts shell-only and installs the published BleedingDev
+package aliases:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app
+```
+
+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.
+
+## Development
+
+Run `pnpm run dev` in the project to start the project:
+
+```bash
+$ pnpm run dev
+> modern dev
+
+  Modern.js Framework
+
+ready   Client compiled in 0.86 s
+
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+Open `http://localhost:8080/` in your browser to see the page content.
+
+## Configuration
+
+In an UltraModern.js project created using `@bleedingdev/modern-js-create`, a `modern.config.ts` file is generated by default.
+
+You can modify the configuration through this file to override the default behavior of Modern.js. For example, to enable SSR, add the following configuration:
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: true,
+  },
+  plugins: [appTools()],
+});
+```
+
+After running `pnpm run dev` again, you can find that the project has completed page rendering on the server in the browser's Network menu.
+
+## Core npm Package
+
+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 `modern dev`, `modern build`, and more.
+- It integrates Rsbuild, providing build capabilities.
+- It integrates Modern.js Server, providing capabilities for development and production servers.
+
+`@modern-js/app-tools` is implemented based on the plugin system of Modern.js. Essentially, it is a plugin. Therefore, you need to register `appTools` in the `plugins` field of the configuration file:
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  plugins: [appTools()],
+});
+```
+
+## Build the project
+
+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.md).
+
+## Verify
+
+Run `pnpm run serve` in the project to verify whether the build artifacts run normally locally:
+
+```bash
+$ pnpm run serve
+
+  Modern.js Framework
+
+info    Starting production server...
+
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+Open `http://localhost:8080/` in the browser, and the content should be consistent with that of `pnpm run dev`.
+
+## Deployment
+
+After local develop, you can refer to the [Deployment](/guides/basic-features/deploy.md) section to deploy the project to the server.

package/docs/guides/get-started/{tech-stack.mdx → tech-stack.md}

@@ -1,7 +1,3 @@
----
-sidebar_position: 4
----
-
 # Tech Stack
 
 The Modern.js framework comes with built-in popular libraries and development tools from the community.
@@ -27,7 +23,7 @@ When creating an UltraModern project, TanStack Router is included by default:
 pnpm dlx @bleedingdev/modern-js-create myapp
 ```
 
-Modern.js supports conventional routing, self-controlled routing, or other routing schemes. Please refer to ["Routing"](/guides/basic-features/routes/routes) to make your choice.
+Modern.js supports conventional routing, self-controlled routing, or other routing schemes. Please refer to ["Routing"](/guides/basic-features/routes/routes.md) to make your choice.
 
 ## Package Manager
 
@@ -53,9 +49,9 @@ During production builds, Modern.js uses [SWC](https://swc.rs/) to minify JS cod
 
 Modern.js uses [PostCSS](https://postcss.org/) to transform CSS code and enables [autoprefixer](https://github.com/postcss/autoprefixer) by default to add CSS prefixes.
 
-Modern.js supports enabling ["Lightning CSS"](/configure/app/tools/lightningcss-loader), which uses Lightning CSS to downgrade CSS syntax.
+Modern.js supports enabling ["Lightning CSS"](/configure/app/tools/lightningcss-loader.md), which uses Lightning CSS to downgrade CSS syntax.
 
-Modern.js supports enabling ["Tailwind CSS"](/guides/basic-features/css/tailwindcss) and is compatible with both Tailwind CSS v3 and v4.
+Modern.js supports enabling ["Tailwind CSS"](/guides/basic-features/css/tailwindcss.md) and is compatible with both Tailwind CSS v3 and v4.
 
 ## CSS Preprocessors
 
@@ -68,11 +64,11 @@ Modern.js supports three CSS preprocessors: [Sass](https://sass-lang.com/), [Les
 
 Modern.js provides out-of-the-box support for [CSS Modules](https://github.com/css-modules/css-modules), which is implemented internally based on [css-loader](https://www.npmjs.com/package/css-loader).
 
-Please refer to ["Use CSS Modules"](/guides/basic-features/css/css-modules) for usage instructions.
+Please refer to ["Use CSS Modules"](/guides/basic-features/css/css-modules.md) for usage instructions.
 
 ## CSS-in-JS
 
-Modern.js supports the use of [styled-components](https://styled-components.com/). Please refer to ["Using CSS-in-JS"](/en/guides/basic-features/css/css-in-js) for usage instructions.
+Modern.js supports the use of [styled-components](https://styled-components.com/). Please refer to ["Using CSS-in-JS"](/guides/basic-features/css/css-in-js.md) for usage instructions.
 
 If you need to use other CSS-in-JS solutions, you can integrate them into your project on your own.
 
@@ -82,16 +78,14 @@ Modern.js can be used with any React UI component library from the community, su
 
 ## Component Development
 
-Modern.js supports the use of [Storybook](https://storybook.js.org/) for developing UI components. This feature is optional. Please refer to ["Using Storybook"](/guides/basic-features/debug/using-storybook) to enable it.
+Modern.js supports the use of [Storybook](https://storybook.js.org/) for developing UI components. This feature is optional. Please refer to ["Using Storybook"](/guides/basic-features/debug/using-storybook.md) to enable it.
 
 ## Testing Framework
 
-Modern.js recommends [Rstest](https://rstest.rs/) for unit tests and component tests. Rstest is built on Rspack for fast startup and execution, and it can reuse your Modern.js app configuration through [`@modern-js/adapter-rstest`](/guides/basic-features/testing/rstest).
+Modern.js recommends [Rstest](https://rstest.rs/) for unit tests and component tests. Rstest is built on Rspack for fast startup and execution, and it can reuse your Modern.js app configuration through [`@modern-js/adapter-rstest`](/guides/basic-features/testing/rstest.md).
 
-For end-to-end (E2E) tests, you can use [Playwright](/guides/basic-features/testing/playwright).
+For end-to-end (E2E) tests, you can use [Playwright](/guides/basic-features/testing/playwright.md).
 
 ## Node.js Framework
 
-import TechStackNodeFramework from '@site-docs-en/components/tech-stack-node-framework';
-
-<TechStackNodeFramework />
+Modern.js Server uses [Hono.js](https://hono.dev/) as the server runtime framework. For BFF, `bff.runtimeFramework` defaults to `effect`, while `hono` remains an explicit compatibility runtime. Effect and Hono BFF runtimes are strict modes (no implicit fallback). You can extend the Server based on the Hono.js ecosystem; refer to [Custom Web Server](/guides/advanced-features/web-server.md).

package/docs/guides/get-started/{ultramodern.mdx → ultramodern.md}

@@ -1,8 +1,3 @@
----
-title: UltraModern.js 3.0
-sidebar_position: 2
----
-
 # UltraModern.js 3.0 vs Modern.js 3.0
 
 This page compares **UltraModern.js 3.0** with the Modern.js 3.x line this fork tracks. The baseline is the current merged Modern.js `release-v3.x` baseline, not a frozen patch-version snapshot.
@@ -32,19 +27,19 @@ or migrated as UltraModern HTTP API, it must use the strict Effect HttpApi path.
 
 ## Intentional Differences (v3 line)
 
-| Area | Modern.js 3.0 baseline | UltraModern.js 3.0 |
-| --- | --- | --- |
-| Build diagnostics | RsDoctor is generally opt-in | Adds a first-class `performance.rsdoctor` config surface (opt-in; the earlier default-on behavior and diagnostics contract artifact were reverted) |
-| Output and static serving | Precompression behavior is app-defined | Enables `output.precompress` by default and serves `.br` / `.gz` variants via `Accept-Encoding` negotiation |
-| BFF runtime and contracts | Standard BFF runtime/client generation | Adds `requestId`-aware producer isolation, fail-fast initialization checks, and operation/trace correlation headers |
-| BFF runtime choices | Standard request-handler oriented BFF paths | Uses Effect `HttpApi` as the only generated HTTP API path (`api/index.ts`, `shared/api.ts`, `src/api/*`) and rejects raw handlers, manual parsing, manual `Response` construction, and Hono server imports in generated workspaces |
-| Telemetry standardization | Observability wiring is often app-specific | Adds framework-level telemetry pipeline with OTLP/VictoriaMetrics exporters, redaction, batching, and backpressure controls |
-| App-level MF SSR handshake | No dedicated super-app app-level stability contract focus | Adds `server.ssr.moduleFederationAppSSR` plus integration-tested env/config handshake |
-| MF vertical loading reliability | Retry/fallback patterns are often implemented per app | Adds deterministic timeout/network/contract-error reliability matrix and distributed OTEL continuity tests |
-| Module onboarding governance | No module-certification evidence profile in baseline | Adds module SDK contracts, boundary anti-pattern guards, and release/module certification gate workflows |
-| Router runtime | Default runtime path centers on React Router | Adds first-class TanStack Router runtime/CLI path (React Router remains supported) |
-| Scaffolding templates | Default create templates center on React Router starter path | Generates a SuperApp workspace by default with TanStack, Effect, Module Federation, i18n, Tailwind, Cloudflare, and ownership contracts |
-| Workspace preset enforcement | No generated UltraModern preset gate workflow | Generated workspaces include `.github/workflows/ultramodern-workspace-gates.yml`, `pnpm check`, primitive local gates, and generated contract validation |
+| Area                            | Modern.js 3.0 baseline                                       | UltraModern.js 3.0                                                                                                                                                                                                                 |
+| ------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Build diagnostics               | RsDoctor is generally opt-in                                 | Adds a first-class `performance.rsdoctor` config surface (opt-in; the earlier default-on behavior and diagnostics contract artifact were reverted)                                                                                 |
+| Output and static serving       | Precompression behavior is app-defined                       | Enables `output.precompress` by default and serves `.br` / `.gz` variants via `Accept-Encoding` negotiation                                                                                                                        |
+| BFF runtime and contracts       | Standard BFF runtime/client generation                       | Adds `requestId`-aware producer isolation, fail-fast initialization checks, and operation/trace correlation headers                                                                                                                |
+| BFF runtime choices             | Standard request-handler oriented BFF paths                  | Uses Effect `HttpApi` as the only generated HTTP API path (`api/index.ts`, `shared/api.ts`, `src/api/*`) and rejects raw handlers, manual parsing, manual `Response` construction, and Hono server imports in generated workspaces |
+| Telemetry standardization       | Observability wiring is often app-specific                   | Adds framework-level telemetry pipeline with OTLP/VictoriaMetrics exporters, redaction, batching, and backpressure controls                                                                                                        |
+| App-level MF SSR handshake      | No dedicated super-app app-level stability contract focus    | Adds `server.ssr.moduleFederationAppSSR` plus integration-tested env/config handshake                                                                                                                                              |
+| MF vertical loading reliability | Retry/fallback patterns are often implemented per app        | Adds deterministic timeout/network/contract-error reliability matrix and distributed OTEL continuity tests                                                                                                                         |
+| Module onboarding governance    | No module-certification evidence profile in baseline         | Adds module SDK contracts, boundary anti-pattern guards, and release/module certification gate workflows                                                                                                                           |
+| Router runtime                  | Default runtime path centers on React Router                 | Adds first-class TanStack Router runtime/CLI path (React Router remains supported)                                                                                                                                                 |
+| Scaffolding templates           | Default create templates center on React Router starter path | Generates a SuperApp workspace by default with TanStack, Effect, Module Federation, i18n, Tailwind, Cloudflare, and ownership contracts                                                                                            |
+| Workspace preset enforcement    | No generated UltraModern preset gate workflow                | Generated workspaces include `.github/workflows/ultramodern-workspace-gates.yml`, `pnpm check`, primitive local gates, and generated contract validation                                                                           |
 
 ## What We Intentionally Do Not Change
 
@@ -425,9 +420,9 @@ The generated `presetUltramodern(...)` starter enables strict platform contracts
 
 ## Related Docs
 
-- [BFF Runtime Frameworks](/guides/advanced-features/bff/frameworks)
-- [BFF Data Platform](/guides/advanced-features/bff/data-platform)
-- [BFF Effect Runtime Config](/configure/app/bff/effect)
-- [Module Federation SSR](/guides/topic-detail/module-federation/ssr)
-- [performance.rsdoctor](/configure/app/performance/rsdoctor)
-- [server.ssr](/configure/app/server/ssr)
+- [BFF Runtime Frameworks](/guides/advanced-features/bff/frameworks.md)
+- [BFF Data Platform](/guides/advanced-features/bff/data-platform.md)
+- [BFF Effect Runtime Config](/configure/app/bff/effect.md)
+- [Module Federation SSR](/guides/topic-detail/module-federation/ssr.md)
+- [performance.rsdoctor](/configure/app/performance/rsdoctor.md)
+- [server.ssr](/configure/app/server/ssr.md)

package/docs/guides/get-started/{upgrade.mdx → upgrade.md}

@@ -1,15 +1,5 @@
----
-sidebar_position: 3
----
-
-import { PackageManagerTabs } from '@theme';
-import ReleaseNote from '@site-docs-en/components/release-note';
-
 # Upgrading
 
-import Upgrade from '@site-docs/components/auto-upgrade';
-
-<Upgrade />
 
 ## Manual Upgrade
 
@@ -24,7 +14,7 @@ All Modern.js official packages are released with a **uniform version number**,
    - Visit [npm](https://www.npmjs.com/package/@modern-js/app-tools) to check the latest version of `@modern-js/app-tools`
    - Check [GitHub Releases](https://github.com/web-infra-dev/modern.js/releases)
 
-   <ReleaseNote />
+According to the [Release Note](https://github.com/web-infra-dev/modern.js/releases) on the official website, developers can also manually upgrade the project to the desired version.
 
 2. **Update package.json**
 
@@ -46,7 +36,26 @@ All Modern.js official packages are released with a **uniform version number**,
 
    After updating `package.json`, reinstall dependencies:
 
-   <PackageManagerTabs command="install" />
+
+```sh [npm]
+npm install
+```
+
+```sh [yarn]
+yarn install
+```
+
+```sh [pnpm]
+pnpm install
+```
+
+```sh [bun]
+bun install
+```
+
+```sh [deno]
+deno install
+```
 
 :::tip
 When upgrading, you need to upgrade all packages provided by Modern.js uniformly, rather than upgrading individual dependencies. Ensure that all `@modern-js/**` packages have the same version number.

package/docs/guides/topic-detail/module-federation/{application.mdx → application.md}

@@ -2,7 +2,7 @@
 
 Modern.js provides runtime APIs to quickly export application-level Module Federation modules from your application.
 
-We use the application created in [Using Module Federation](/guides/topic-detail/module-federation/usage) as an example to further explain how to import application-level modules.
+We use the application created in [Using Module Federation](/guides/topic-detail/module-federation/usage.md) as an example to further explain how to import application-level modules.
 
 ## Exporting Modules from Producer
 
@@ -62,7 +62,7 @@ export default createModuleFederationConfig({
 ```
 
 :::info
-[`createBridgeComponent`](https://module-federation.io/guide/bridge/overview#core-apis) is used to export application-level modules. Modern.js related APIs can be found at [createRoot](/apis/app/runtime/core/create-root) and [render](/apis/app/runtime/core/render).
+[`createBridgeComponent`](https://module-federation.io/guide/bridge/overview#core-apis) is used to export application-level modules. Modern.js related APIs can be found at [createRoot](/apis/app/runtime/core/create-root.md) and [render](/apis/app/runtime/core/render.md).
 :::
 
 ## Using Modules in Consumer
@@ -72,7 +72,7 @@ We then modify the consumer configuration by removing the previously created `sr
 We want all routes that access `/remote` to enter the aforementioned application-level module, so we add `src/routes/remote/$.tsx` instead.
 
 :::note
-If you are not familiar with the capabilities of `$.tsx`, please read [Wildcard Routes](/guides/basic-features/routes/routes#wildcard-routes).
+If you are not familiar with the capabilities of `$.tsx`, please read [Wildcard Routes](/guides/basic-features/routes/routes.md#wildcard-routes).
 :::
 
 ```tsx title="src/routes/remote/$.tsx"

package/docs/guides/topic-detail/module-federation/{deploy.mdx → deploy.md}

@@ -5,7 +5,7 @@ In general, when deploying a Module Federation application, there are two key po
 1. Ensure that the remote module addresses in the consumer's configuration file are correct, and that the consumer can correctly access the producer's `manifest` file.
 2. Ensure that all resources in the producer's `manifest` file can be accessed correctly.
 
-We recommend using Modern.js's [Node Server](/guides/basic-features/deploy.html#using-modernjs-built-in-nodejs-server) to deploy Module Federation applications for an out-of-the-box experience.
+We recommend using Modern.js's [Node Server](/guides/basic-features/deploy.md#using-modernjs-built-in-nodejs-server) to deploy Module Federation applications for an out-of-the-box experience.
 
 ## Consumer
 
@@ -36,7 +36,7 @@ In the above code, the address of the remote module is `/static/mf-manifest.json
 
 ## Producer
 
-For the producer of Module Federation, developers need to correctly configure the [`output.assetPrefix`](/configure/app/output/asset-prefix) configuration, which affects:
+For the producer of Module Federation, developers need to correctly configure the [`output.assetPrefix`](/configure/app/output/asset-prefix.md) configuration, which affects:
 
 1. The `publicPath` defined in `mf-manifest.json`, which determines the access path of other resources of the remote module.
 2. The access path of the `mf-manifest.json` file when hosted directly by the Modern.js server.