@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/en/guides/get-started/ultramodern.mdx

@@ -0,0 +1,98 @@
+---
+title: UltraModern.js
+sidebar_position: 2
+---
+
+# UltraModern.js v3 vs Modern.js v3
+
+This page compares **UltraModern.js v3** with **Modern.js v3** (baseline: `v3.0.2`).
+
+UltraModern.js serves here as the reference name for the public `presetUltramodern(...)` Modern.js profile. The goal is to harden the baseline for super-app and ERP-scale systems without forking Modern.js into a separate framework.
+
+## Design Principles
+
+- Keep deltas small and explicit.
+- Preserve the upstream Modern.js mental model and mergeability.
+- Add platform-level contracts only where they improve cross-team reliability.
+- Keep opt-out switches and explicit compatibility lanes available.
+
+## Compatibility Contract
+
+UltraModern.js v3 keeps:
+
+- Modern.js app/config/plugin mental model.
+- Existing project structure and command flow.
+- Progressive adoption path (apps can stay mostly unchanged).
+
+UltraModern additions are designed to land as stronger defaults, explicit compatibility lanes, or auditable gates rather than as a separate product surface.
+
+## Intentional Differences (v3 line)
+
+| Area | Modern.js v3 baseline | UltraModern.js v3 |
+| --- | --- | --- |
+| Build diagnostics | RsDoctor is generally opt-in | Adds `performance.rsdoctor`, default-on diagnostics in production Rspack builds, and `.rsdoctor/ultramodern-diagnostics.json` contract artifact |
+| 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 | Hono runtime path only in Modern.js v3 baseline (no built-in Effect runtime path) | Sets Effect as default runtime, enforces strict runtime split (`effect` -> `api/effect`, `hono` -> `api/lambda`), and adds Effect-Schema-first contracts plus MF failure-injection reliability coverage |
+| 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 remote 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 | Adds TanStack-ready and Tailwind-ready create templates |
+| Starter preset enforcement | No generated UltraModern preset gate workflow | Generated starters include `ultramodern:check`, opt-out env switches, and `.github/workflows/ultramodern-gates.yml` |
+
+## What We Intentionally Do Not Change
+
+- We do not fork core architecture into a separate framework model.
+- We do not replace normal Modern.js defaults for teams that do not need super-app contracts.
+- We keep both runtime modes (`effect`, `hono`) as explicit choices and avoid implicit fallback between them.
+- We avoid incompatible API changes unless there is a hard reliability requirement.
+
+## Adoption Notes
+
+For teams already on Modern.js v3, the path remains compatibility-first: keep the Modern.js mental model, move toward MV-first / TanStack-first / Effect-first defaults, and keep fallback lanes explicit while you adopt the stronger profile.
+
+1. Keep existing React Router apps running as-is. TanStack Router is the preferred path for new scaffolds and incremental route adoption, but the React Router lane remains supported while teams move on their own schedule.
+2. Prefer `bff.runtimeFramework: 'effect'` for new BFF work, with the entry implemented at `api/effect/index.ts`. If your app already uses Hono handlers under `api/lambda/**`, keep `bff.runtimeFramework: 'hono'` until you are ready to move them; Hono remains a supported compatibility lane.
+3. Treat the baseline contracts as progressive defaults, not a forced cutover. `MODERN_BASELINE_ENABLE_MF_SSR`, `MODERN_BASELINE_ENABLE_BFF_REQUEST_ID`, and `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` already let each app opt out while it converges on the preferred stack.
+4. The public preset now ships with explicit release and certification gates. The generated starter also ships `.github/workflows/ultramodern-gates.yml`, so `pnpm run ultramodern:check` and `pnpm run build` stay part of the adoption contract from day one.
+
+This page is not a migration guide or codemod plan. Migration guidance for existing applications is intentionally deferred from the current Micro Verticals framework scope.
+
+## Micro Vertical Delivery Path
+
+`presetUltramodern(...)` is also the single public entrypoint for Micro Verticals. The intended adoption sequence is:
+
+1. start with one app and keep route/data ownership inside the shell,
+2. extract stable route subtrees into MF remotes once fallback and compatibility behavior are explicit,
+3. extract shared workflows into strict Effect services when request, identity, locale, and trace context must survive deployment boundaries,
+4. keep Hono only as an explicit compatibility lane for existing Modern.js-style BFF handlers.
+
+In this repo, the reference examples are:
+
+- `routes-tanstack-mf` for shell + remote composition and MF SSR contracts,
+- `bff-corss-project` for cross-project producer/consumer wiring,
+- `bff-runtime-parity` for generated-client build/serve parity,
+- `bff-hono` for the compatibility lane.
+
+## 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)
+- [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)

package/docs/en/guides/get-started/upgrade.mdx

@@ -0,0 +1,114 @@
+---
+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
+
+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)
+
+   <ReleaseNote />
+
+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:
+
+   <PackageManagerTabs command="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 the `package.json` in the **root directory** of the project, and then run `pnpm install` again:
+
+```json title="package.json"
+{
+  "pnpm": {
+    "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, you can only lock dependency versions in the `package.json` in the root directory of the project, and it will affect all packages in the Monorepo.
+
+:::

package/docs/en/guides/topic-detail/_meta.json

@@ -0,0 +1,8 @@
+[
+  {
+    "type": "dir",
+    "name": "module-federation",
+    "label": "module-federation",
+    "collapsed": true
+  }
+]

package/docs/en/guides/topic-detail/module-federation/_meta.json

@@ -0,0 +1 @@
+["introduce", "usage", "application", "ssr", "deploy", "i18n"]

package/docs/en/guides/topic-detail/module-federation/application.mdx

@@ -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) 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/practice/bridge/react-bridge/export-app.html#createbridgecomponent-api-reference) 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).
+:::
+
+## 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#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/zh/practice/bridge/react-bridge/load-app.html#%E4%BB%80%E4%B9%88%E6%98%AF-createremoteappcomponent) 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-examples/tree/main/examples/module-federation/app-export).
+
+## Related Documentation
+
+- [Module Federation Bridge](https://module-federation.io/zh/practice/bridge/index.html)

package/docs/en/guides/topic-detail/module-federation/deploy.mdx

@@ -0,0 +1,104 @@
+# Deployment
+
+In general, when deploying a Module Federation application, there are two key points to consider:
+
+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.
+
+## Consumer
+
+For the consumer of Module Federation, its connection with the producer is the remote module address in the configuration file.
+
+For example, if the producer is deployed under the domain `https://my-remote-module`, the developer needs to modify the consumer's configuration file:
+
+```ts title="module-federation.config.ts"
+import { createModuleFederationConfig } from '@module-federation/modern-js-v3';
+
+export default createModuleFederationConfig({
+  name: 'host',
+  remotes: {
+    remote: 'remote@https://my-remote-module/static/mf-manifest.json',
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+});
+```
+
+At this point, the consumer will load the `manifest` configuration file of the remote module production environment.
+
+:::note
+In the above code, the address of the remote module is `/static/mf-manifest.json`, which is just an example using the default output path of Modern.js. In actual projects, developers need to configure according to the actual access path.
+:::
+
+## Producer
+
+For the producer of Module Federation, developers need to correctly configure the [`output.assetPrefix`](/configure/app/output/asset-prefix) 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.
+
+In the production environment, developers need to configure `output.assetPrefix` as the access path of the production environment. For example, if we deploy the producer under the domain `https://my-remote-module`, we need to configure `output.assetPrefix` as `https://my-remote-module`.
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  output: {
+    assetPrefix: 'https://my-remote-module',
+  },
+});
+```
+
+At this point, the `publicPath` defined in the producer's build output `mf-manifest.json` is `https://my-remote-module`, for example:
+
+```json
+{
+  "id": "remote",
+  "name": "remote",
+  "metaData": {
+    "name": "remote",
+    "publicPath": "https://my-remote-module/"
+  },
+  "shared": [ /* xxx */ ],
+  "remotes": [],
+  "exposes": [ /* xxx */ ]
+}
+```
+
+When the consumer accesses the remote module, it will automatically prepend the `publicPath` to the resource path of the remote module.
+
+This configuration will also affect the access path of the producer's `mf-manifest.json`. For example, if this value is set to `MyDomain/module-a`, the hosting path of `mf-manifest.json` becomes `MyDomain/module-a/static/mf-manifest.json`.
+
+At this point, the consumer needs to configure the following address when configuring the remote module:
+
+```ts title="module-federation.config.ts"
+import { createModuleFederationConfig } from '@module-federation/modern-js-v3';
+
+export default createModuleFederationConfig({
+  name: 'host',
+  remotes: {
+    remote: 'remote@MyDomain/module-a/static/mf-manifest.json',
+  },
+});
+```
+
+## Local Deployment Verification
+
+Modern.js provides the `modern deploy` command, which can easily generate products that can run in a Node.js environment.
+
+```bash
+modern deploy
+```
+
+After executing the command, you can see the following output in the console:
+
+```bash
+Static directory: .output/static
+You can preview this build by node .output/index
+```
+
+At this point, the developer only needs to run `node .output/index` to preview the effect locally. Whether it is a CSR or an SSR application, all Module Federation files can be accessed correctly.