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

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

@@ -1,403 +0,0 @@
----
-title: UltraModern.js 3.0
-sidebar_position: 6
----
-
-# UltraModern.js 3.0 vs Modern.js 3.0
-
-UltraModern.js 3.0 is our SuperApp framework forked from Modern.js for large, independently deployable super-app and ERP-style systems.
-
-This page is the complete public difference reference for the UltraModern.js 3.0 framework line.
-
-## Scope (3.0 Only)
-
-- Baseline: the current merged Modern.js `release-v3.x` baseline tracked by this fork; this page should not be read as a frozen patch-version comparison.
-- Scope: all user-visible differences shipped in UltraModern.js 3.0.
-- Excluded: roadmap/mainline-only work that is not shipped to UltraModern.js 3.0.
-
-## Complete Difference Matrix (3.0)
-
-| Area | Modern.js 3.0 baseline | UltraModern.js 3.0 difference | Status in 3.0 | Notes |
-| --- | --- | --- | --- | --- |
-| Build diagnostics default | RsDoctor usage is opt-in in most projects | Rspack production build enables RsDoctor by default | Implemented | Can be disabled via `performance.rsdoctor` |
-| Build diagnostics config surface | No `performance.rsdoctor` option in framework docs | Adds `performance.rsdoctor` (`boolean` or `{ enabled, disableClientServer, reportDir, mode }`) | Implemented | `disableClientServer` defaults to `true` |
-| Diagnostics artifact contract | No standardized machine-readable diagnostics pointer | Adds `.rsdoctor/ultramodern-diagnostics.json` contract pointing to manifest | Implemented | Stable consumption path for coding agents |
-| Static asset precompression defaults | Precompressed artifacts and serving are app-defined | Adds default-on `output.precompress` for production web builds and static middleware `Accept-Encoding` negotiation for `.br` / `.gz` | Implemented | Can be disabled or tuned per codec |
-| Router runtime choice | Default runtime path centers on React Router | Adds first-class TanStack Router runtime/CLI route tree support | Implemented | React Router path remains available |
-| Scaffolding template path | Default create templates center on React Router starter path | Adds TanStack-ready and Tailwind-ready create templates | Implemented | React Router starter path remains available |
-| Starter preset gate workflow | Generated starter has no UltraModern preset verification workflow | Adds `ultramodern:check`, opt-out env switches, and `.github/workflows/ultramodern-gates.yml` to the public preset starter | Implemented | Keeps generated apps auditable from the first commit |
-| BFF producer contract wiring | `bff` config does not include producer identity | Adds `bff.requestId` and carries it through client generation | Implemented | Enables explicit producer scoping |
-| Generated BFF client call shape | `createRequest(...)` optional args stop at `fetch` | Generated client appends `requestId` to `createRequest(...)` when configured | Implemented | Keeps legacy call path when no `requestId` |
-| `create-request` runtime isolation | Single mutable request config path | Per-`requestId` request/domain/header config maps | Implemented | Supports multiple producer clients in one app |
-| BFF audit correlation headers | No standardized producer audit propagation for operation and trace | Adds `x-operation-id`, `x-modernjs-bff-operation-context`, and `traceparent` propagation with parsed trace IDs | Implemented | Supports tenant/operation/trace joins in observability |
-| Uninitialized producer behavior | Missing config may silently fall back | Non-default `requestId` now throws `ProducerClientNotInitializedError` | Implemented | Fail-fast contract for cross-project BFF |
-| Node header forwarding behavior | Header forwarding is global | Incoming headers are forwarded only for `requestId === 'default'` | Implemented | Avoids accidental header bleed across producers |
-| Server telemetry config | No standardized `server.telemetry` contract | Adds `server.telemetry` with sampling/batching/redaction/exporter settings | Implemented | Added to app-tools schema and server types |
-| Telemetry exporters | Export pipeline is app-defined | Built-in OTLP and VictoriaMetrics exporters | Implemented | Exporters are non-fatal on failure |
-| Telemetry backpressure contract | No standard queue policy | Registry queue with max size, dropped-event counter, periodic flush | Implemented | Emits `telemetry.queue.dropped` on pressure |
-| Metrics/trace correlation | SSR metrics tags do not parse W3C trace context | `traceparent` is parsed and emits `trace_id` / `span_id` tags | Implemented | Improves cross-system observability joins |
-| App-level MF SSR contract flag | No dedicated app-level MF SSR stability contract switch | Adds `server.ssr.moduleFederationAppSSR` contract and auto-enables env wiring when MF SSR markers are detected | Implemented | Sets `process.env.MODERN_MF_APP_SSR` |
-| App-level MF SSR runtime bridge | Not a stable default bridge path | V3 applies stable bridge defaults for MF SSR node output/runtime env when server rendering + MF markers are present | Implemented | Keeps explicit opt-out path via config/env |
-| MF vertical loading reliability contracts | Loading fallback patterns are typically app-defined | Adds deterministic timeout/network/contract-error fallback matrix and distributed OTEL continuity assertions | Implemented | `routes-tanstack-mf` reliability suite |
-| BFF runtime choices | Hono runtime path only in Modern.js 3.0 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-only MF data contracts plus failure-injection coverage for federated data fetch | Implemented (Effect-default + strict split) | Stream is explicit about no Zod introduction |
-| Module SDK contract artifact | No framework-level module contract artifact | Adds machine-readable module contract + typed module SDK interfaces | Implemented | `module-sdk-contracts.json` + `moduleSdk.d.ts` |
-| Boundary anti-pattern CI guards | No dedicated boundary anti-pattern workflow | Adds profile-driven CI checks for boundary imports, required hooks, and forbidden module patterns | Implemented | `.github/workflows/boundary-anti-patterns.yml` |
-| Release/module certification gate automation | No super-app release evidence profile in baseline | Adds RC + module-certification gate profiles, evidence metadata validation, and dedicated CI workflows | Implemented | `.github/workflows/release-contract-gates.yml` + module/bun gate workflows |
-| Contract test coverage | No tests for these new contracts in the tracked Modern.js 3.x baseline | Adds focused tests for RsDoctor defaults, BFF requestId, telemetry, SSR MF contract env wiring | Implemented | Reduces regression risk in super-app scenarios |
-| Public docs surface | No UltraModern V3 comparison page | Adds dedicated V3 difference page and linked config docs | Implemented | This page is the reference page for the public preset profile |
-
-## Detailed 3.0 Differences
-
-### 1) `performance.rsdoctor` and default-on diagnostics
-
-UltraModern.js 3.0 extends performance config with:
-
-- `performance.rsdoctor: boolean | { enabled?: boolean; disableClientServer?: boolean; reportDir?: string; mode?: 'normal' | 'brief' | 'lite' }`
-- Rspack + production: enabled by default.
-- Rspack + development: disabled by default (unless explicitly enabled).
-- Webpack builds: no RsDoctor injection.
-- RsDoctor contract artifact:
-  - `<reportDir or outputPath>/.rsdoctor/ultramodern-diagnostics.json`
-  - points to `.rsdoctor/manifest.json`
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  performance: {
-    rsdoctor: {
-      enabled: true,
-      disableClientServer: true,
-      reportDir: './artifacts',
-      mode: 'brief',
-    },
-  },
-});
-```
-
-### 2) Cross-project BFF hardening with `requestId`
-
-UltraModern.js 3.0 adds explicit producer identity across the BFF toolchain:
-
-- `bff.requestId` in plugin config.
-- Loader/client generation passes `requestId` to `createRequest(...)`.
-- `create-request` now keeps isolated runtime state per `requestId`.
-
-```ts
-configure({
-  requestId: 'erp-inventory',
-  request: customFetch,
-  setDomain: ({ target, requestId }) =>
-    target === 'server'
-      ? `http://inventory-bff.internal`
-      : `https://inventory.example.com`,
-});
-```
-
-Contract behavior in 3.0:
-
-- Non-default producer calls without prior `configure({ requestId })` throw `ProducerClientNotInitializedError`.
-- `allowedHeaders` / `request` / `setDomain` are isolated by `requestId`.
-- In Node runtime, incoming request headers are only forwarded for the legacy `default` producer path.
-- Non-default producer calls emit operation context and trace correlation headers:
-  - `x-operation-id`
-  - `x-modernjs-bff-operation-context`
-  - `traceparent` (with parsed `traceId` / `spanId` reflected in operation context when present)
-
-### 3) `server.telemetry` standardization and exporters
-
-UltraModern.js 3.0 adds a unified telemetry contract:
-
-- Config surface in `server.telemetry`.
-- Internal registry with sampling, batching, redaction, backpressure handling.
-- Built-in exporters for OTLP and VictoriaMetrics.
-- Metrics wrapper that mirrors `emitCounter` / `emitTimer` into telemetry envelopes.
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  server: {
-    telemetry: {
-      enabled: true,
-      service: 'erp-gateway',
-      module: 'server',
-      environment: 'production',
-      samplingRate: 1,
-      flushIntervalMs: 1000,
-      maxBatchSize: 50,
-      maxQueueSize: 1000,
-      redactionKeys: ['authorization', 'token'],
-      exporters: {
-        otlp: {
-          enabled: true,
-          endpoint: 'http://otel-collector:4318/v1/logs',
-        },
-        victoriaMetrics: {
-          enabled: true,
-          endpoint: 'http://vm:8428/api/v1/import/prometheus',
-          metricPrefix: 'ultramodern',
-        },
-      },
-    },
-  },
-});
-```
-
-Important V3 behavior:
-
-- If no exporter is enabled, telemetry pipeline is not initialized.
-- Exporter failures are treated as non-fatal for request handling.
-
-### 4) Trace tags in SSR metrics
-
-When an incoming request contains W3C `traceparent`, UltraModern.js 3.0 parses and injects:
-
-- `trace_id`
-- `span_id`
-
-into SSR metric tags, improving correlation between app metrics and distributed tracing backends.
-
-### 5) App-level MF SSR stable contract (`server.ssr.moduleFederationAppSSR`)
-
-UltraModern.js 3.0 adds:
-
-- Preferred flag: `server.ssr.moduleFederationAppSSR` (also works under `server.ssrByEntries`).
-- Global compile-time env:
-  - `process.env.MODERN_MF_APP_SSR` (`'true' | 'false'`)
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  server: {
-    ssr: {
-      moduleFederationAppSSR: true,
-    },
-  },
-});
-```
-
-When MF SSR markers are detected in server-rendered entries, V3 now enables the same env/bridge contract path by default and keeps config/env switches as explicit opt-out controls.
-
-### 6) Contract-level test hardening in V3
-
-UltraModern.js 3.0 adds dedicated coverage for:
-
-- RsDoctor default behavior and opt-out semantics.
-- BFF `requestId` generation/runtime isolation and fail-fast checks.
-- Telemetry redaction/backpressure/exporter behavior.
-- SSR MF contract detection and env injection.
-
-### 7) Module SDK contract + boundary anti-pattern guards
-
-UltraModern.js 3.0 adds platform-boundary enforcement artifacts for module onboarding:
-
-- Contract artifact: `docs/super-app-rfc-adr/contracts/module-sdk-contracts.json`
-- Example manifest: `docs/super-app-rfc-adr/contracts/module-manifest.example.json`
-- Public type contracts: `packages/toolkit/types/common/moduleSdk.d.ts`
-- Validation tooling:
-  - `scripts/module-sdk-contracts/validate-module-sdk-contracts.js`
-  - `scripts/boundary-guards/check-boundary-violations.js`
-- CI workflow:
-  - `.github/workflows/boundary-anti-patterns.yml`
-  - `.github/workflows/module-certification-gates.yml`
-  - `.github/workflows/bun-superapp-smoke.yml`
-
-### 8) Default precompression + precompressed static serving
-
-UltraModern.js 3.0 changes default output and serving behavior for production web assets:
-
-- `output.precompress` defaults to `true` in app-tools config.
-- Build emits gzip (`.gz`) and brotli (`.br`) variants for static assets.
-- Node static middleware selects precompressed variants via `Accept-Encoding` and sets:
-  - `Content-Encoding`
-  - `Vary: Accept-Encoding`
-- Codec-level tuning is supported per project (`gzip` / `brotli` options).
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  output: {
-    precompress: {
-      gzip: true,
-      brotli: {
-        threshold: 8 * 1024,
-      },
-    },
-  },
-});
-```
-
-### 9) First-class TanStack Router + Tailwind scaffolding
-
-UltraModern.js 3.0 adds a first-class TanStack path in runtime and project scaffolding:
-
-- Runtime/CLI support for TanStack route tree generation and SSR/stream integration.
-- Create templates include TanStack-ready scaffolds and Tailwind starter wiring.
-- Dedicated integration suites cover:
-  - `tests/integration/routes-tanstack`
-  - `tests/integration/routes-tanstack-mf`
-- Existing React Router workflow remains supported.
-
-### 10) Effect-first MF data reliability and data-platform contracts
-
-UltraModern.js 3.0 shipped additional reliability work aligned to Beads stream D:
-
-- `@modern-js/plugin-bff` runtime path migrated to Effect v4.
-- Effect-only MF data-fetch contract guidance (explicitly no Zod layer in this stream).
-- MF vertical loading reliability matrix includes deterministic failure injection (timeout/network/contract error).
-- Distributed trace continuity checks were re-enabled for build and serve paths.
-- Data-platform architecture defines operation identity, envelope integrity, scoped invalidation, and trace propagation contracts.
-
-Reference materials:
-
-- `docs/super-app-rfc-adr/ADR-0003-effect-only-mf-data-fetch-reliability.md`
-- `packages/cli/plugin-bff/docs/data-platform-architecture.md`
-- `routes-tanstack-mf` reliability coverage
-
-### 11) Release and module certification gate model
-
-UltraModern.js 3.0 includes a machine-verifiable gate model beyond baseline Modern.js 3.0:
-
-- Gate profiles:
-  - `scripts/release-gates/rc-contract-profile.json`
-  - `scripts/release-gates/module-certification-profile.json`
-- Required evidence contracts under:
-  - `docs/super-app-rfc-adr/evidence/release-candidate/current`
-  - `docs/super-app-rfc-adr/evidence/module-certification/current`
-- Local validation commands:
-  - `pnpm run validate:module-sdk-contracts`
-  - `pnpm run validate:boundary-guards`
-  - `pnpm run validate:module-certification-gates`
-  - `pnpm run validate:rc-gates`
-  - `pnpm run validate:bun-smoke`
-- CI workflows:
-  - `.github/workflows/release-contract-gates.yml`
-  - `.github/workflows/module-certification-gates.yml`
-  - `.github/workflows/bun-superapp-smoke.yml`
-- Generated starter workflow:
-  - `.github/workflows/ultramodern-gates.yml`
-  - runs `pnpm run ultramodern:check` and `pnpm run build`
-
-## Not Part of UltraModern.js 3.0
-
-The following are intentionally out of scope for this public V3 preset profile:
-
-- Forcing Effect-only data-fetch runtime as the mandatory default for every app.
-- Forcing app-level MF SSR for every app regardless of readiness.
-
-## Human Workflow
-
-The public BleedingDev create package starts small. The default command creates
-one production-ready UltraModern app with `presetUltramodern(...)`, SSR,
-TanStack Router, Tailwind CSS v4, i18n, Effect BFF, generated quality gates, and
-production URL metadata:
-
-```bash
-pnpm dlx @bleedingdev/modern-js-create myapp
-cd myapp
-mise install
-pnpm install
-pnpm run ultramodern:check
-MODERN_PUBLIC_SITE_URL=https://example.com pnpm build
-```
-
-Create a SuperApp workspace only when independent ownership is useful:
-
-```bash
-pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
-cd my-super-app
-mise install
-pnpm install
-pnpm check
-pnpm build
-```
-
-The initial SuperApp workspace is shell-only: `apps/shell-super-app` owns route
-assembly and Module Federation host wiring, `verticals/*` starts empty, and
-`packages/shared-*` holds placeholders for contracts, tokens, and API support.
-Add verticals only when a real business domain needs independent ownership.
-
-Add real business MicroVerticals as they become 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
-pnpm check
-pnpm build
-```
-
-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.
-
-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` and serves dynamic backend JSON from
-`/locales/{{lng}}/{{ns}}.json`.
-
-The generated contract writes `.modernjs/ultramodern-generated-contract.json`
-with `cssFederation`: shared design tokens stay in `packages/shared-design-tokens`,
-shell CSS owns shell layers, each vertical owns one CSS layer with app-local
-prefixes, and SSR first paint uses Modern/Rspack assets plus manifest-owned
-vertical CSS.
-
-Generated workspaces include `scripts/proof-cloudflare-version.mjs` for live
-Cloudflare and Zephyr proof. Deploy first, then pass each deployed app's
-generated public URL env key into the proof step. Shell-only workspaces only
-need the shell URL; added verticals use the same
-`ULTRAMODERN_PUBLIC_URL_<APP_ID>` pattern with hyphens converted to underscores
-and uppercased.
-
-```bash
-pnpm cloudflare:deploy
-ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev \
-ULTRAMODERN_PUBLIC_URL_TRANSPORTATION=https://transportation.example.workers.dev \
-pnpm cloudflare:proof -- --require-public-urls
-```
-
-Live proof requires public Worker URLs and Zephyr credentials; local checks
-still validate generated contracts, builds, Cloudflare output, dry-run Zephyr
-evidence plans, and local evidence schemas.
-
-## Current Troubleshooting
-
-| Symptom | Current check | Owner |
-| --- | --- | --- |
-| Package cohort mismatch | Regenerate with one package source strategy, run `mise install`, then rerun `pnpm install` from the activated shell. | Generated workspace package source metadata |
-| Install failure | Check the active Node/pnpm from `mise install`; rerun `pnpm install` after the shell sees the pinned versions. | Toolchain setup |
-| Build failure | Run `pnpm check` before `pnpm build`; fix reported format, lint, type, skill, i18n, or generated-contract failures first. | Owning package or generated contract |
-| Missing public URL | Set the env key from `.modernjs/ultramodern-generated-contract.json`, for example `ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP`. | Deployment operator |
-| Cloudflare credentials | Confirm Wrangler credentials before `pnpm cloudflare:deploy`; local checks do not prove live Worker access. | Deployment operator |
-| Asset or CSS 404 | Rebuild with `pnpm build` or `pnpm cloudflare:deploy` and inspect emitted Modern/Rspack asset paths instead of hardcoding CSS URLs. | Framework/runtime asset pipeline |
-| Federation manifest failure | Run the shell and vertical build scripts, then check each deployed `/mf-manifest.json` URL used by the shell. | Module Federation owner |
-
-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(...)` create template enables stricter platform contracts. These env switches are read by generated `modern.config.ts` and can be disabled/overridden 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 Public Docs
-
-- [performance.rsdoctor](/configure/app/performance/rsdoctor)
-- [server.ssr](/configure/app/server/ssr)
-- [BFF guide](/guides/advanced-features/bff/index)
-- [BFF frameworks](/guides/advanced-features/bff/frameworks)
-- [BFF data platform architecture](/guides/advanced-features/bff/data-platform)
-- [BFF Effect runtime config](/configure/app/bff/effect)
-- [Micro-frontend guide](/guides/topic-detail/micro-frontend/c01-introduction)
-- [Module Federation SSR](/guides/topic-detail/module-federation/ssr)