@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.98 → 3.8.1-ultramodern.1

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

@@ -0,0 +1,440 @@
+# 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.
+
+UltraModern.js 3.0 is our SuperApp framework forked from Modern.js. It keeps the Modern.js plugin/runtime mental model where that helps adoption, but it is positioned as a separate framework for Effect HttpApi-first HTTP APIs, TanStack Router, SSR, Module Federation, and independently deployable Micro Verticals.
+
+## Design Principles
+
+- Keep deltas explicit and auditable.
+- Keep upstream Modern.js merge compatibility explicit: generic Modern.js runtime
+  code can remain where it belongs, while UltraModern-generated surfaces stay
+  strict.
+- Add platform-level contracts only where they improve cross-team reliability.
+- Keep escape hatches explicit and outside the generated HTTP API path.
+
+## Compatibility Contract
+
+UltraModern.js 3.0 keeps:
+
+- Modern.js app/config/plugin mental model.
+- Existing project structure and command flow.
+- Progressive adoption path (apps can stay mostly unchanged).
+
+UltraModern.js additions are designed as the default product surface for new SuperApps. The framework direction is Effect + TanStack + SSR + Micro Verticals, and generated HTTP API work uses that direction by default instead of preserving parallel raw-handler layouts.
+Existing Modern.js apps can migrate gradually; once an API surface is generated
+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                                                                           |
+
+## What We Intentionally Do Not Change
+
+- We do not hide the fork behind legacy Modern.js branding.
+- We do not optimize for generic Modern.js defaults when they conflict with SuperApp reliability.
+- We do not delete generic Modern.js Hono/file-convention runtime support just
+  to enforce UltraModern policy; the enforcement lives in UltraModern
+  generator, config, checks, and generated workspaces.
+- Generated UltraModern API work uses the Effect runtime only; raw Hono/function handlers are not part of the generated API architecture.
+- We make incompatible scaffold changes when they remove architecture drift.
+
+## Migration Guide
+
+For teams already on Modern.js 3.0 or an older BleedingDev UltraModern scaffold, the adoption path is to move API work onto the strict Effect HttpApi surface instead of preserving older raw handler layouts.
+
+1. Keep existing Modern.js apps running as-is while they are outside the generated UltraModern surface. TanStack Router is the preferred path for new scaffolds and incremental route adoption, but route migration can happen on the team's schedule.
+2. Use `bff.runtimeFramework: 'effect'` with `bff.effect.strictEffectApproach: true` for API work. Entries live at `api/index.ts`, contracts live at `shared/api.ts`, clients live under `src/api/*`, and request/response/error shapes come from Effect `Schema` plus `HttpApi`.
+3. Treat raw handlers, `api/lambda/**`, manual `Response` construction, and manual request parsing as migration defects in generated or migrated UltraModern workspaces.
+4. The public preset now ships with explicit release and certification gates. Generated workspaces include `.github/workflows/ultramodern-workspace-gates.yml`, so `pnpm check` and `pnpm build` stay part of the local adoption contract from day one while CI runs the primitive gates as parallel matrix jobs.
+
+For an older generated workspace, migrate by treating the published cohort as
+the source of truth:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create@latest --help
+pnpm dlx @bleedingdev/modern-js-create@latest catalog --vertical --dry-run
+pnpm dlx @bleedingdev/modern-js-create@latest catalog --vertical
+mise install
+mise exec -- pnpm install
+mise exec -- pnpm check
+mise exec -- pnpm build
+```
+
+### Migrating to `3.5.0-ultramodern.18`
+
+Use `3.5.0-ultramodern.18` or newer for localized Cloudflare SSR workspaces.
+This cohort moves bare locale-root redirects into the framework-owned
+Cloudflare Worker entry and the i18n server runtime. A request for `/` is
+redirected server-side with `302` to the negotiated locale path, for example
+`/cs` for `Accept-Language: cs-CZ` or `/en` for English and fallback traffic.
+
+Existing generated workspaces should upgrade the whole BleedingDev Modern
+package cohort together:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create@3.5.0-ultramodern.18 ultramodern \
+  migrate-strict-effect --version 3.5.0-ultramodern.18
+pnpm install
+pnpm check
+pnpm build
+pnpm cloudflare:build
+```
+
+For deployed Cloudflare Workers, redeploy after the cohort update and verify
+the root response before accepting the migration:
+
+```bash
+curl -I -H 'Accept-Language: cs-CZ,cs;q=0.9,en;q=0.1' https://<worker-host>/
+```
+
+The expected response is `302` with `Location: /cs` or the matching locale,
+`Cache-Control: private, no-store`, and `Vary` covering the locale detection
+headers. Following the redirect should return the SSR locale page with the
+matching document language and i18n SSR data.
+
+Do not fix older root `404` responses by adding app-owned root route files,
+client-side redirects, custom navigation wrappers, Cloudflare Worker
+postprocessing, generated output edits, or local redirect shims. If `/` still
+returns `404` after upgrading, confirm the production build log shows
+`Modern.js Framework v3.5.0-ultramodern.18` or newer and redeploy the Worker.
+
+Strict generated API migration requires `3.5.0-ultramodern.10` or newer.
+`3.4.0-ultramodern.20` and earlier cohorts do not include this full direct
+`api/index.ts` generator, generated `.mts` checks, strict Oxlint boundary rule
+set, Effect cohort overrides, and strict Effect migration command. Agents that
+cannot install that BleedingDev cohort yet should use the local Modern.js
+workspace for migration validation; otherwise pin `3.5.0-ultramodern.10` or
+newer with `--ultramodern-package-version`.
+
+Before hand-editing package aliases or generated metadata, run the framework
+migration command from the target workspace:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create@3.5.0-ultramodern.10 ultramodern \
+  migrate-strict-effect --version 3.5.0-ultramodern.10
+pnpm api:check
+pnpm contract:check
+```
+
+The command updates `.modernjs/ultramodern.json`, root
+`modernjs.packageSource`, generated Modern package aliases, framework-owned
+toolchain pins, direct topology API metadata, strict Effect pnpm
+overrides/trust policy, and the pnpm lockfile. Remaining failures are source
+migration work: move code to `shared/api.ts`, `api/index.ts`, and
+`src/api/*-client.ts`, then delete `api/effect`, `api/lambda`, `shared/effect`,
+and `src/effect`.
+
+Generated strict Effect workspaces pin the compatible Effect cohort with pnpm
+overrides: `effect@4.0.0-beta.107`, `@effect/opentelemetry@4.0.0-beta.107`,
+and `@effect/vitest@4.0.0-beta.107`. Do not add app-local direct Effect
+versions that disagree with those overrides. The strict 24-hour release-age
+gate applies to installed packages; this cohort carries no Effect age
+exemption, and override-only `@effect/vitest` is not an installed approval
+target. Independently, exact `trustPolicyExclude` entries for `effect`
+and `@effect/opentelemetry` cover their trusted-publisher to provenance
+metadata transition; they are not release-age approvals.
+
+### Current generated dependency baseline
+
+| Surface                        | Pin                                                                                                 |
+| ------------------------------ | --------------------------------------------------------------------------------------------------- |
+| Effect runtime and test cohort | `effect`, `@effect/opentelemetry`, and `@effect/vitest`: `4.0.0-beta.107`                           |
+| Effect compiler                | `@effect/tsgo@0.36.2`                                                                               |
+| TanStack Router                | `@tanstack/react-router@1.170.25`, `@tanstack/router-core@1.171.21`, `@tanstack/history@1.162.1`    |
+| Module Federation              | `bridge-react`, `manifest`, `modern-js-v3`, and `rspack`: `2.8.2`; `@module-federation/node@2.7.49` |
+| React Router                   | `react-router@7.18.2`                                                                               |
+| Node and package tooling       | Node `26.7.0`, `@types/node@^26.2.0`, pnpm `11.21.0`                                                |
+
+Gradual migration means old, unmigrated Modern.js apps can keep their existing
+runtime until they are converted. Once a surface is generated or migrated as
+UltraModern HTTP API, it uses Effect HttpApi only; do not keep Hono, lambda
+handlers, or raw request handlers inside that UltraModern API surface.
+
+When migrating a generated workspace that already has nested Effect API files, make the
+move explicit and do not keep compatibility aliases:
+
+1. Move each vertical server entry from `verticals/<id>/api/effect/index.ts` to
+   `verticals/<id>/api/index.ts`.
+2. Move each shared API contract from `verticals/<id>/shared/effect/api.ts` to
+   `verticals/<id>/shared/api.ts`.
+3. Move generated clients from `verticals/<id>/src/effect/*-client.ts` to
+   `verticals/<id>/src/api/*-client.ts`.
+4. Move shell API aggregates from `apps/shell-super-app/src/effect/*` to
+   `apps/shell-super-app/src/api/*`.
+5. Update imports and package exports to use `./api`, `./api/client`, and
+   `@<workspace>/<vertical>/api/client`; remove `./effect/client`,
+   `./shared/effect/api`, and shared Effect API packages.
+6. Update every vertical `modern.config.ts` to use
+   `bff.effect.entry: './api/index'` and
+   `bff.effect.strictEffectApproach: true`.
+7. Update topology so API metadata lives directly under `api` with
+   `api.bff.strictEffectApproach: true`; do not keep `api.effect`.
+8. Run `pnpm api:check`,
+   `scripts/validate-ultramodern-workspace.mts`, `pnpm check`, and
+   `pnpm build`.
+
+If a migration fails, fix the owning generated contract, topology, package
+exports, or API module. Do not add app-level aliases, raw request handlers,
+manual `Response` construction, local type casts, or package shims to make the
+old layout pass.
+
+Effect RPC, WebSockets, and other transports should be added as explicit
+transport surfaces when needed. They do not make raw request handlers valid
+inside generated HTTP API modules.
+
+Strict API tests should exercise the `HttpApi` contract. Use
+`createEffectBffTestHandler` from `@modern-js/plugin-bff/effect-edge` for
+edge-compatible proof tests; if you manually compose a web handler, provide
+`HttpServer.layerServices` beside your API group layer before calling
+`HttpRouter.toWebHandler`.
+
+For dynamic origin CORS predicates inside strict Effect HTTP APIs, prefer
+`HttpRouter.middleware(Effect.succeed(HttpMiddleware.cors(...)))`.
+`HttpRouter.middleware(...)` returns a `Layer` directly in the pinned Effect
+cohort; do not read a `.layer` property from it.
+
+Use one package-source strategy per repo. The published BleedingDev create
+package defaults to `--ultramodern-package-source=install` and records the
+exact cohort in `.modernjs/ultramodern.json`. Keep `--workspace` only for local
+monorepo testing against unreleased packages. Release proof and CI should pin
+the exact cohort with `--ultramodern-package-version` when a repo must prove a
+specific published framework version.
+
+Older repos with nested Effect entries and `verbatimModuleSyntax` should update to
+the latest BleedingDev cohort instead of adding app-level `"type": "module"`
+metadata, Module Federation shims, or custom server wrappers. The framework BFF
+compiler normalizes CommonJS server output while generated app packages keep
+stable TypeScript 7 so Module Federation DTS generation and TS-Go checks use
+the same modern compiler lane.
+
+Cloudflare SSR deploys are also split by runtime responsibility: `.output` is an
+ESM module-worker package, while `.output/worker` remains a CommonJS package
+scope for the worker bundles emitted by Modern.js SSR builds. Do not fix older
+repos by hand-editing generated worker output; upgrade the framework cohort and
+rerun the generated validation instead.
+
+After installing the new cohort, run the generated
+`scripts/validate-ultramodern-workspace.mts` contract check before accepting
+manual edits. Fix topology, ownership, package-source, local overlay, generated
+contract, Tailwind prefix, or Module Federation conflicts in the owning files
+instead of patching generated output by hand.
+
+Cloudflare D1 bindings are first-class on `deploy.worker.d1Databases`; use that
+config instead of app-local postprocessing when a generated app owns D1
+migrations. Cloudflare public output excludes server-only `api` and `shared`
+directories by default, and generated Modern/Rspack output roots, temp
+directories, and caches are isolated per app, build target, and Rspack
+environment so local `build`, `cloudflare:build`, and multi-environment
+compilers do not share mutable build state.
+
+## Human Workflow
+
+The public BleedingDev create package has one supported generated product. The
+default command creates a production-ready UltraModern SuperApp workspace with
+`presetUltramodern(...)`, SSR, TanStack Router, Tailwind CSS v4, i18n, Effect
+BFF, Module Federation topology, generated quality gates, and Cloudflare deploy
+basics:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create myapp
+cd myapp
+mise install
+mise exec -- pnpm install
+mise exec -- pnpm check
+```
+
+The workspace starts from a shell and generated platform contracts. It does not
+generate a demo domain by default. Add real business MicroVerticals when they
+become real ownership boundaries:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical
+pnpm dlx @bleedingdev/modern-js-create food-delivery --vertical
+pnpm dlx @bleedingdev/modern-js-create payments --vertical
+pnpm dlx @bleedingdev/modern-js-create maps --vertical
+mise exec -- pnpm check
+```
+
+The `--vertical` command mutates the current workspace. It creates the vertical
+package and updates topology metadata, ownership records, shell Module
+Federation wiring, local development overlays, package dependencies, generated
+contracts, ports, route-owned i18n, CSS isolation, and the vertical-owned Effect
+BFF/client surface.
+
+### Generator Automation
+
+Automation can use explicit MicroVertical syntax instead of relying on the
+positional form:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create --vertical=transportation
+pnpm dlx @bleedingdev/modern-js-create --vertical-name transportation
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical --dry-run
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical \
+  --codesmith-overlay ./generators/vertical-overlay
+```
+
+The BleedingDev package defaults to installing the published package cohort.
+Use `--workspace` or `--ultramodern-package-source=workspace` for local monorepo
+testing. Release proof and package-source automation can also pass
+`--ultramodern-package-source=install`,
+`--ultramodern-package-version`, `--ultramodern-package-registry`,
+`--ultramodern-package-scope`, and
+`--ultramodern-package-name-prefix`.
+
+The supported public generator import is:
+
+```ts
+import {
+  addUltramodernVertical,
+  generateUltramodernWorkspace,
+  planUltramodernVertical,
+} from '@modern-js/create/ultramodern-workspace';
+
+const workspace = generateUltramodernWorkspace({
+  targetDir: '/tmp/my-workspace',
+  packageName: 'my-workspace',
+  modernVersion: '3.4.0',
+});
+
+const plan = planUltramodernVertical({
+  workspaceRoot: workspace.workspaceRoot,
+  name: 'transportation',
+  modernVersion: '3.4.0',
+});
+
+addUltramodernVertical({
+  workspaceRoot: workspace.workspaceRoot,
+  name: 'transportation',
+  modernVersion: '3.4.0',
+  overlays: [{ generator: './generators/vertical-overlay' }],
+});
+```
+
+The public result includes the workspace root, package source, created apps,
+created paths, rewritten paths, assigned ports, Module Federation names, API
+prefixes, generated contract path, and warnings. MicroVertical dry-run
+returns the same shape plus `dryRun`, `selectedPort`, `moduleFederationRemote`,
+`apiPrefix`, `jsonMutations`, `shellDependencyChanges`, and
+`generatedContractChanges`; it prints JSON from the CLI and writes no files.
+
+CodeSmith consumers can use the adapter subpath:
+
+```ts
+import ultramodernCodeSmith from '@modern-js/create/ultramodern-workspace/codesmith';
+
+await ultramodernCodeSmith({
+  config: {
+    mode: 'vertical',
+    name: 'transportation',
+    workspaceRoot: process.cwd(),
+    dryRun: true,
+    logResult: true,
+  },
+});
+```
+
+Validation runs before the first write and reports the owning contract when a
+vertical name is missing or invalid, an existing topology already owns the app
+ID/path/package suffix/port/Module Federation name/API prefix/manifest key, a
+workspace JSON contract is missing or not an object, or a Tailwind prefix would
+collide. Fix the workspace contract or choose a different vertical name before
+rerunning.
+
+Overlays are explicit CodeSmith generators that run after base workspace or
+MicroVertical generation. They extend generated output; they do not replace,
+inherit, or shadow the base templates. The generator and CodeSmith adapter are
+plain Node generator surfaces. The package build emits declaration files through
+the TS-Go toolchain. Generated app packages keep stable `typescript` on TS7 so
+Module Federation DTS generation and TS-Go use the same compiler lane; runtime
+code does not depend on compiler internals.
+
+### Runtime Contracts
+
+Generated apps and verticals keep SSR on the normal Modern.js path. SuperApp
+workspaces add `server.ssr.moduleFederationAppSSR` when Module Federation SSR is
+needed, but the flag remains an explicit contract rather than a requirement for
+every app.
+
+Each app emits `src/routes/ultramodern-route-metadata` with
+`ultramodernLocalisedUrls`. The i18n plugin reads that map in
+`localeDetection.localisedUrls`; this is the explicit non-empty map that enables
+translated path segments on top of `localePathRedirect`. The i18n plugin also
+serves dynamic backend JSON from `/locales/{{lng}}/{{ns}}.json`. The route owner
+changes localized paths and locale resource JSON together.
+
+JSON-LD is optional route metadata, not inferred output. Private and
+non-indexable routes emit no JSON-LD by default. Public route owners can add
+`jsonLd` beside localized paths and use the generated
+`src/routes/ultramodern-jsonld.ts` helpers for common schema.org shapes.
+
+The generated contract writes `.modernjs/ultramodern.json` with a
+`cssFederation` section:
+
+- `packages/shared-design-tokens` owns the shared token layer and exports `./tokens.css`.
+- Shell CSS owns only shell base and overlay layers under `[data-app-id="shell-super-app"]`.
+- Each vertical owns one CSS layer, for example `[data-app-id="vertical-transportation"]` with app-local class prefixes.
+- Tailwind CSS v4 is local to each generated app through `@rsbuild/plugin-tailwindcss`; shared base styles must not be duplicated by verticals.
+- SSR first paint requires shared token CSS and app-owned CSS to be emitted by Modern/Rspack assets. Vertical CSS is loaded through manifest ownership, not copied into shell source.
+
+Version switching must select UI, API, CSS, i18n JSON, and MF manifest evidence from the same vertical build marker. A shell render that only changes the UI marker is not enough.
+
+### Validation And Deploy
+
+Local gates:
+
+```bash
+mise exec -- pnpm check
+mise exec -- pnpm build
+mise exec -- pnpm cloudflare:build
+```
+
+Generated workspaces include `scripts/proof-cloudflare-version.mjs` for live
+Cloudflare and Zephyr proof:
+
+```bash
+ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_TRANSPORTATION=https://transportation.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_PAYMENTS=https://payments.example.workers.dev \
+mise exec -- pnpm cloudflare:proof --require-public-urls
+```
+
+Live Cloudflare and Zephyr proof requires public Worker URLs and Zephyr credentials. Without those, the repo can validate generated contracts, local builds, local Cloudflare output, dry-run Zephyr evidence plans, and local evidence schemas, but it cannot prove shell-driven live version selection.
+
+BleedingDev packages are published through GitHub Actions trusted publishing.
+The public workflow is tokenless; do not publish packages manually from a
+developer machine.
+
+## Baseline Switches (Opt-out)
+
+The generated `presetUltramodern(...)` starter enables strict platform contracts. Use these env switches to opt out per app or per environment:
+
+- `MODERN_BASELINE_ENABLE_MF_SSR` (default: `true`): Enables app-level MF SSR baseline contract (`server.ssr.mode: 'stream'` + `moduleFederationAppSSR`). Disable when the app does not use app-level MF SSR, or when you need plain SSR/CSR behavior first.
+- `MODERN_BASELINE_ENABLE_BFF_REQUEST_ID` (default: `true`): Enables default BFF producer identity contract (`bff.requestId`). Disable when the app does not need cross-project producer isolation.
+- `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` (default: `true`): Enables telemetry exporters in baseline config. Disable when the environment has no telemetry backend yet.
+- `MODERN_BASELINE_APP_ID` (default: `basename(process.cwd())`): Overrides baseline `bff.requestId` identity. Set this when you need a fixed platform-wide producer ID convention.
+- `MODERN_TELEMETRY_OTLP_ENDPOINT` (default: `http://127.0.0.1:4318/v1/logs`): OTLP exporter endpoint. Override when you route telemetry through a different collector endpoint.
+- `MODERN_TELEMETRY_VICTORIA_ENDPOINT` (default: `http://127.0.0.1:8428/api/v1/import/prometheus`): VictoriaMetrics exporter endpoint. Override when you use a different VM ingress endpoint.
+- `MODERN_TELEMETRY_FAIL_LOUD_STARTUP` (default: `true`): Fails startup if configured exporters fail startup health checks. Disable in local/dev environments where temporary telemetry outage should not block boot.
+
+## Related Docs
+
+- [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.md

@@ -0,0 +1,118 @@
+# Upgrading
+
+
+## Manual Upgrade
+
+All Modern.js official packages are released with a **uniform version number**, so when upgrading, you need to update all `@modern-js/**` packages to the target version uniformly.
+
+### Upgrade Steps
+
+1. **Check the latest version**
+
+   You can check the latest version of Modern.js through the following methods:
+
+   - 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)
+
+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**
+
+   In the project's `package.json`, update all `@modern-js/**` packages to the target version. For example:
+
+   ```json title="package.json"
+   {
+     "dependencies": {
+       "@modern-js/app-tools": "3.0.0",
+       "@modern-js/runtime": "3.0.0"
+     },
+     "devDependencies": {
+       "@modern-js/types": "3.0.0"
+     }
+   }
+   ```
+
+3. **Reinstall dependencies**
+
+   After updating `package.json`, reinstall dependencies:
+
+
+```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.
+:::
+
+## Version Management Strategy
+
+In Modern.js projects, we recommend that all officially provided dependencies use fixed version, and avoid using `^` or `~` for range declarations. For example:
+
+```json
+{
+  "dependencies": {
+    "@modern-js/app-tools": "x.y.z"
+  }
+}
+```
+
+This ensures that the versions of dependencies are fully determined, thereby guaranteeing build consistency and predictability.
+
+## Lock nested dependency
+
+When a nested dependency of the project has a problem and Modern.js cannot be updated immediately, you can use the package manager to lock the version of the nested dependency.
+
+### pnpm
+
+For projects using pnpm, add the following configuration to `pnpm-workspace.yaml` in the **root directory** of the project, and then run `pnpm install` again:
+
+```yaml title="pnpm-workspace.yaml"
+overrides:
+  package-name: ^1.0.0
+```
+
+### Yarn
+
+For projects using Yarn, add the following configuration to the `package.json` in the **root directory** of the project, and then run `yarn install` again:
+
+```json title="package.json"
+{
+  "resolutions": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+### Npm
+
+For projects using Npm, add the following configuration to the `package.json` in the **root directory** of the project, and then run `npm install` again:
+
+```json title="package.json"
+{
+  "overrides": {
+    "package-name": "^1.0.0"
+  }
+}
+```
+
+:::info
+For Monorepo repositories, lock dependency versions in the package-manager configuration at the project root. The override affects every package in the Monorepo.
+
+:::

package/docs/guides/topic-detail/module-federation/application.md

@@ -0,0 +1,116 @@
+# Application-Level Modules
+
+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.md) as an example to further explain how to import application-level modules.
+
+## Exporting Modules from Producer
+
+Unlike directly exporting component-level modules, we need to create a separate entry for application-level modules to be exported via `Module Federation`.
+
+We create the `src/export-App.tsx` file:
+
+:::note
+The filename can be arbitrary; Modern.js does not enforce a specific naming convention.
+:::
+
+```ts title="src/export-App.tsx"
+import '@modern-js/runtime/registry/index'; // This line must be included, it will import micro frontend runtime dependencies by default
+import { render } from '@modern-js/runtime/browser';
+import { createRoot } from '@modern-js/runtime/react';
+import { createBridgeComponent } from '@module-federation/modern-js-v3/react-v19';
+
+const ModernRoot = createRoot();
+export const provider = createBridgeComponent({
+  rootComponent: ModernRoot,
+  render: (Component, dom) => render(Component, dom),
+});
+
+export default provider;
+```
+
+:::note
+Please select the corresponding import path based on the React version used in your project:
+
+- **React 19**: Use `@module-federation/modern-js-v3/react-v19`
+- **React 18**: Use `@module-federation/modern-js-v3/react-v18`
+
+You can check the React version in your project's `package.json` file to determine which import path to use.
+:::
+
+This file will pass the root component of the `main` entry application to the Bridge API and render it to the specified node via Bridge's render function.
+
+Next, we configure `module-federation.config.ts` to modify the export to `src/export-App.tsx`:
+
+```ts title="module-federation.config.ts"
+import { createModuleFederationConfig } from '@module-federation/modern-js-v3';
+
+export default createModuleFederationConfig({
+  name: 'remote',
+  manifest: {
+    filePath: 'static',
+  },
+  filename: 'static/remoteEntry.js',
+  exposes: {
+    './app': './src/export-App.tsx',
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+});
+```
+
+:::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.md) and [render](/apis/app/runtime/core/render.md).
+:::
+
+## Using Modules in Consumer
+
+We then modify the consumer configuration by removing the previously created `src/routes/remote/page.tsx` route file.
+
+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.md#wildcard-routes).
+:::
+
+```tsx title="src/routes/remote/$.tsx"
+import { createRemoteAppComponent } from '@module-federation/modern-js-v3/react';
+import { loadRemote } from '@module-federation/modern-js-v3/runtime';
+
+const ErrorBoundary = (info?: { error: { message: string } }) => {
+  return (
+    <div>
+      <h2>This is ErrorBoundary Component, Something went wrong:</h2>
+      <pre style={{ color: 'red' }}>{info?.error.message}</pre>
+    </div>
+  );
+};
+const Loading = <div>loading...</div>;
+const RemoteApp = createRemoteAppComponent({
+  loader: () => loadRemote('remote/app'),
+  fallback: ErrorBoundary,
+  loading: Loading,
+});
+
+export default RemoteApp;
+```
+
+:::info
+[`createRemoteAppComponent`](https://module-federation.io/guide/bridge/overview#core-apis) is used to load application-level modules.
+:::
+
+## Start the Application
+
+Now, both the producer and consumer applications are set up. We can run `modern dev` locally to start both applications.
+
+After startup, when the consumer application accesses the `/remote` route, it will enter the producer application. Accessing `http://localhost:8080/remote` will display a complete page of the producer's remote module in the browser.
+
+You can create new route files in the producer application and add route navigation in the code. These functionalities will also work as expected.
+
+You can refer to the example here: [Modern.js & Module Federation Application-Level Modules](https://github.com/web-infra-dev/modern.js/tree/main/examples/module-federation/app-export).
+
+## Related Documentation
+
+- [Module Federation Bridge](https://module-federation.io/guide/bridge/overview)