@bleedingdev/modern-js-create 3.2.0-ultramodern.81 → 3.2.0-ultramodern.83

package/README.md

@@ -27,24 +27,20 @@ To initialize the empty directory you are already in, pass `.` explicitly:
 pnpm dlx @bleedingdev/modern-js-create .
 ```
 
-Create a full SuperApp workspace only when you need independently owned
-verticals:
+The default is the full UltraModern single-app setup. Create a SuperApp
+workspace explicitly when you need independently owned verticals:
 
 ```bash
 pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
 ```
 
-The workspace is a full-stack reference, not a visual-only commerce boundary
-demo. It generates:
+The workspace starts shell-only so the first commit has no fake business
+domains to delete. It generates:
 
 - `apps/shell-super-app` as the Module Federation host and topology owner.
-- `verticals/explore` for discovery UI plus
-  `/explore-api/effect/explore/*`.
-- `verticals/decide` for product selection UI plus
-  `/decide-api/effect/decide/*`.
-- `verticals/checkout` for cart and checkout UI plus
-  `/checkout-api/effect/checkout/*`.
-- `packages/shared-design-tokens` as the shared CSS token owner.
+- `verticals/*` empty until you add a real domain with `--vertical`.
+- `packages/shared-*` placeholders for shared contracts, tokens, and API
+  support.
 - `.modernjs/ultramodern-generated-contract.json` with MF, Effect, i18n,
   federated CSS, Cloudflare, and Zephyr dependency metadata.
 
@@ -54,13 +50,14 @@ Validate the generated workspace before making application changes:
 cd my-super-app
 mise install
 pnpm install
-pnpm ultramodern:check
+pnpm check
 pnpm build
 ```
 
 ### Router Template
 
-TanStack Router is generated by default. To force the compatibility router:
+TanStack Router is generated by default. Choose React Router only as an explicit
+compatibility lane:
 
 ```bash
 pnpm dlx @bleedingdev/modern-js-create my-app --router react-router
@@ -127,10 +124,10 @@ Use this decision table before adding a vertical:
 | Design tokens, primitives, generated clients, or domain-neutral utilities | Yes | Use an ordinary workspace package, not a vertical |
 | Feature composites or workflow state shared across verticals | No | Revisit ownership; do not hide it in shared code |
 
-The lower-level `--router`, `--workspace`, and `--sub` flags remain available
-for manual package scaffolding, but UltraModern vertical additions should use
-`--vertical` so paths, topology, Effect BFF contracts, and local overlays stay
-consistent.
+The lower-level `--router react-router`, `--workspace`, and `--sub` flags remain
+available for compatibility and local package scaffolding, but UltraModern
+vertical additions should use `--vertical` so paths, topology, Effect BFF
+contracts, and local overlays stay consistent.
 
 See
 `docs/super-app-rfc-adr/WORKSPACE-0001-micro-vertical-workspace-scaffolding.md`
@@ -141,14 +138,13 @@ UltraModern.js entrypoint. The lower-level `--ultramodern-*` flags remain
 available for release engineering and local package-source testing, but users
 should not need them for normal app creation.
 
-### Tractor Architecture Contracts
+### SuperApp Architecture Contracts
 
-The generated shell owns route assembly and policy. The generated Explore,
-Decide, and Checkout verticals own their own route subtree, MF exposes, Effect BFF
-contract, generated client, `localisedUrls`, locale JSON, CSS layer, and
-Cloudflare Worker output. The shell consumes vertical UI through MF manifests
-and vertical APIs through generated Effect clients exported by the vertical
-packages.
+The generated shell owns route assembly and policy. Each vertical added with
+`--vertical` owns its route subtree, MF exposes, Effect BFF contract, generated
+client, `localisedUrls`, locale JSON, CSS layer, and Cloudflare Worker output.
+The shell consumes vertical UI through MF manifests and vertical APIs through
+generated Effect clients exported by the vertical packages.
 
 Route localization is route-owned. Each app writes
 `src/routes/ultramodern-route-metadata` and passes
@@ -176,7 +172,7 @@ manifest markers in lockstep for the same vertical version.
 
 ### Cloudflare And Zephyr Proof
 
-Each generated app has:
+Each generated workspace app has:
 
 - `cloudflare:build`, `cloudflare:deploy`, `cloudflare:preview`, and
   `cloudflare:proof` scripts.
@@ -184,20 +180,33 @@ Each generated app has:
 - `zephyr:dependencies` for any consumed verticals.
 - `zephyr-rspack-plugin` wired through the generated Modern.js Rspack bridge.
 
-Public URL proof is intentionally separate from local build validation:
+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
-ULTRAMODERN_PUBLIC_URL_EXPLORE=https://explore.example.workers.dev \
-ULTRAMODERN_PUBLIC_URL_DECIDE=https://decide.example.workers.dev \
-ULTRAMODERN_PUBLIC_URL_CHECKOUT=https://checkout.example.workers.dev \
+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 Zephyr switching proof requires Zephyr credentials and public runtime,
-manifest, and API URLs for v1 and v2 of Explore, Decide, and Checkout. Without
-public URLs and credentials, use dry-run evidence only; do not claim live
-Zephyr selection has been proven.
+Without public URLs and credentials, use local `pnpm check` and `pnpm build`
+evidence only; do not claim live Cloudflare or Zephyr selection has been
+proven.
+
+### 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 |
 
 ### Local Monorepo Testing
 
@@ -208,14 +217,14 @@ workspace protocol dependencies:
 pnpm dlx @bleedingdev/modern-js-create my-app --workspace
 ```
 
-For package-source validation of the full Tractor workspace, generate with the
+For package-source validation of the full SuperApp workspace, generate with the
 workspace package source, then run the generated contract gate:
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create tractor-super-app --ultramodern-workspace --ultramodern-package-source workspace
-cd tractor-super-app
+pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace --ultramodern-package-source workspace
+cd my-super-app
 pnpm install
-pnpm ultramodern:check
+pnpm check
 ```
 
 ## Documentation

package/dist/index.js

@@ -465,12 +465,12 @@ const EN_LOCALE = {
         optionHelp: '  -h, --help     Display this help message',
         optionVersion: '  -v, --version  Display version information',
         optionLang: '  -l, --lang     Set the language (zh or en)',
-        optionRouter: '  -r, --router   Select router framework (react-router or tanstack)',
+        optionRouter: '  -r, --router   Select router framework (tanstack default; react-router is compatibility mode)',
         optionBff: '      --bff      Keep Effect BFF enabled (default for UltraModern apps)',
         optionBffRuntime: '      --bff-runtime Select BFF runtime (hono or effect)',
         optionTailwind: '      --no-tailwind Disable default Tailwind CSS v4 scaffold',
         optionWorkspace: '      --workspace Use workspace protocol for @modern-js dependencies (for local monorepo testing)',
-        optionUltramodernWorkspace: '      --ultramodern-workspace Generate an UltraModern SuperApp workspace (explicit opt-in; default is a simple app)',
+        optionUltramodernWorkspace: '      --ultramodern-workspace Generate an UltraModern SuperApp workspace (default is a full UltraModern single app)',
         optionUltramodernPackageSource: '      --ultramodern-package-source Select UltraModern package source (workspace or install; BleedingDev defaults to install aliases)',
         optionUltramodernPackageScope: '      --ultramodern-package-scope Publish scope for npm alias installs (for example bleedingdev)',
         optionUltramodernPackageNamePrefix: '      --ultramodern-package-name-prefix Prefix for npm alias package names (default: modern-js-)',
@@ -487,7 +487,7 @@ const EN_LOCALE = {
         example8: '  pnpm dlx @bleedingdev/modern-js-create my-app --workspace',
         example9: '  pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace',
         example10: '  pnpm dlx @bleedingdev/modern-js-create my-app --no-tailwind',
-        example11: '  pnpm dlx @bleedingdev/modern-js-create my-app --router react-router',
+        example11: '  pnpm dlx @bleedingdev/modern-js-create my-app --router react-router # compatibility mode',
         example12: '  pnpm dlx @bleedingdev/modern-js-create catalog --vertical',
         moreInfo: '📚 Learn more: https://modernjs.dev'
     },
@@ -523,12 +523,12 @@ const ZH_LOCALE = {
         optionHelp: '  -h, --help     显示帮助信息',
         optionVersion: '  -v, --version  显示版本信息',
         optionLang: '  -l, --lang     设置语言 (zh 或 en)',
-        optionRouter: '  -r, --router   选择路由框架 (react-router 或 tanstack)',
+        optionRouter: '  -r, --router   选择路由框架（默认 tanstack；react-router 为兼容模式）',
         optionBff: '      --bff      保持启用 Effect BFF（UltraModern 应用默认值）',
         optionBffRuntime: '      --bff-runtime 选择 BFF 运行时（hono 或 effect）',
         optionTailwind: '      --no-tailwind 禁用默认 Tailwind CSS v4 模板',
         optionWorkspace: '      --workspace 对 @modern-js 依赖使用 workspace 协议（用于本地 monorepo 联调）',
-        optionUltramodernWorkspace: '      --ultramodern-workspace 生成 UltraModern SuperApp 工作区（显式选择；默认创建简单应用）',
+        optionUltramodernWorkspace: '      --ultramodern-workspace 生成 UltraModern SuperApp 工作区（默认创建完整 UltraModern 单应用）',
         optionUltramodernPackageSource: '      --ultramodern-package-source 选择 UltraModern 依赖来源（workspace 或 install；BleedingDev 默认使用 install alias）',
         optionUltramodernPackageScope: '      --ultramodern-package-scope npm alias 安装使用的发布 scope（例如 bleedingdev）',
         optionUltramodernPackageNamePrefix: '      --ultramodern-package-name-prefix npm alias 包名前缀（默认：modern-js-）',
@@ -545,7 +545,7 @@ const ZH_LOCALE = {
         example8: '  pnpm dlx @bleedingdev/modern-js-create my-app --workspace',
         example9: '  pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace',
         example10: '  pnpm dlx @bleedingdev/modern-js-create my-app --no-tailwind',
-        example11: '  pnpm dlx @bleedingdev/modern-js-create my-app --router react-router',
+        example11: '  pnpm dlx @bleedingdev/modern-js-create my-app --router react-router # 兼容模式',
         example12: '  pnpm dlx @bleedingdev/modern-js-create catalog --vertical',
         moreInfo: '📚 更多信息: https://modernjs.dev'
     },
@@ -1497,7 +1497,7 @@ const createRemoteManifestUrl = (options: {
 `;
 }
 function createModuleFederationRemotesConfig(scope, app, remotes = []) {
-    const remoteEntries = resolveRemoteRefs(app, remotes).map((remote)=>{
+    const remoteEntries = resolveRemoteRefs(app, remotes).toSorted((left, right)=>remoteDependencyAlias(left).localeCompare(remoteDependencyAlias(right))).map((remote)=>{
         const key = remoteDependencyAlias(remote);
         return `    ${key}: createRemoteManifestUrl({
       manifestEnv: '${createRemoteManifestEnv(remote)}',
@@ -1532,6 +1532,9 @@ const reactDomVersion = (require('react-dom/package.json') as { version: string
 
 ${createModuleFederationRemoteUrlHelpers(shellHost, remotes)}
 export default createModuleFederationConfig({
+  bridge: {
+    enableBridgeRouter: false,
+  },
   dev: {
     disableDynamicRemoteTypeHints: true,
   },
@@ -1587,6 +1590,9 @@ const reactDomVersion = (require('react-dom/package.json') as { version: string
 
 ${createModuleFederationRemoteUrlHelpers(app, remotes)}
 export default createModuleFederationConfig({
+  bridge: {
+    enableBridgeRouter: false,
+  },
   dev: {
     disableDynamicRemoteTypeHints: true,
   },
@@ -2350,24 +2356,16 @@ function createShellRemoteComponents(scope, remotes = []) {
         const componentName = `${toPascalCase(remote.id)}Widget`;
         return `const ${componentName} = createHydratedRemote(${componentName}Server, '${remoteDependencyAlias(remote)}/Widget');`;
     }).join('\n');
-    const showcaseItems = widgetRemotes.map((remote)=>{
-        const componentName = `${toPascalCase(remote.id)}Widget`;
-        return `          <${componentName} key="${remote.id}" />`;
-    }).join('\n');
-    const remoteCount = String(widgetRemotes.length);
-    return `import { createLazyComponent } from '@module-federation/bridge-react';
+    const federationImports = widgetRemotes.length > 0 ? `import { createLazyComponent } from '@module-federation/bridge-react';
 import { getInstance, loadRemote } from '@module-federation/modern-js-v3/runtime';
 import { Suspense, useEffect, useMemo, useState } from 'react';
 import type { ComponentType } from 'react';
-import { I18nLink, useModernI18n } from '@modern-js/plugin-i18n/runtime';
 ${serverImports}
-
-interface RemoteComponentModule {
+` : '';
+    const federationHelpers = widgetRemotes.length > 0 ? `interface RemoteComponentModule {
   default: ComponentType;
 }
 
-const widgetCount = Number('${remoteCount}');
-
 const loadRemoteComponent = (specifier: string) =>
   loadRemote<RemoteComponentModule>(specifier) as Promise<RemoteComponentModule>;
 
@@ -2414,10 +2412,20 @@ const createHydratedRemote =
       </Suspense>
     );
   };
+` : '';
+    const showcaseItems = widgetRemotes.map((remote)=>{
+        const componentName = `${toPascalCase(remote.id)}Widget`;
+        return `          <${componentName} key="${remote.id}" />`;
+    }).join('\n');
+    const remoteCount = String(widgetRemotes.length);
+    return `${federationImports}import { I18nLink, useModernI18n } from '@modern-js/plugin-i18n/runtime';
+
+	const widgetCount = Number('${remoteCount}');
 
-${hydratedExports}
+	${federationHelpers}
+	${hydratedExports}
 
-export const Header = () => {
+	export const Header = () => {
   const { i18nInstance } = useModernI18n();
   const t = i18nInstance['t'].bind(i18nInstance);
 

package/package.json

@@ -21,7 +21,7 @@
   "engines": {
     "node": ">=20"
   },
-  "version": "3.2.0-ultramodern.81",
+  "version": "3.2.0-ultramodern.83",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/index.js",
   "bin": {
@@ -41,7 +41,7 @@
     "@types/node": "^25.9.1",
     "@typescript/native-preview": "7.0.0-dev.20260527.2",
     "tsx": "^4.22.3",
-    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.2.0-ultramodern.81"
+    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.2.0-ultramodern.83"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -54,6 +54,6 @@
     "start": "node ./dist/index.js"
   },
   "ultramodern": {
-    "frameworkVersion": "3.2.0-ultramodern.81"
+    "frameworkVersion": "3.2.0-ultramodern.83"
   }
 }

package/template/pnpm-workspace.yaml

@@ -1,6 +1,8 @@
 minimumReleaseAge: 1440
 minimumReleaseAgeStrict: true
 minimumReleaseAgeIgnoreMissingTime: false
+minimumReleaseAgeExclude:
+  - '@bleedingdev/modern-js-*'
 trustPolicy: no-downgrade
 trustPolicyIgnoreAfter: 1440
 blockExoticSubdeps: true

package/template/scripts/validate-ultramodern.mjs.handlebars

@@ -330,8 +330,11 @@ if (readPnpmConfig('minimumReleaseAgeIgnoreMissingTime') !== false) {
   console.error('pnpm minimumReleaseAgeIgnoreMissingTime must be false');
   process.exit(1);
 }
-if (readPnpmConfig('minimumReleaseAgeExclude') !== undefined) {
-  console.error('pnpm minimumReleaseAgeExclude must stay unset');
+if (
+  JSON.stringify(readPnpmConfig('minimumReleaseAgeExclude')) !==
+  JSON.stringify(['@bleedingdev/modern-js-*'])
+) {
+  console.error('pnpm minimumReleaseAgeExclude must allow just-published BleedingDev Modern cohorts only');
   process.exit(1);
 }
 if (readPnpmConfig('trustPolicy') !== 'no-downgrade') {
@@ -420,6 +423,15 @@ if (typeof expectedModernSpecifier !== 'string' || expectedModernSpecifier.lengt
   console.error('Package source metadata must provide a Modern package specifier');
   process.exit(1);
 }
+if (
+  packageSource.strategy === 'install' &&
+  expectedModernSpecifier !== templateManifest.template?.version
+) {
+  console.error(
+    `Package source Modern specifier ${expectedModernSpecifier} must match template version ${templateManifest.template?.version}`,
+  );
+  process.exit(1);
+}
 
 const expectedModernDependency = (packageName) => {
   const alias = packageSource.modernPackages?.aliases?.[packageName];

package/template-workspace/README.md.handlebars

@@ -28,7 +28,9 @@ Run the scaffold validator before adding business code and after every
 
 ```bash
 mise install
-pnpm ultramodern:check
+pnpm install
+pnpm check
+pnpm build
 ```
 
 By default, `pnpm install` also prepares read-only agent reference repositories
@@ -50,3 +52,28 @@ UltraModern.js runtime and tooling packages on `workspace:*` for monorepo
 development. To create a workspace that can install those packages outside the
 monorepo, generate with `--ultramodern-package-source install`; generated shared
 packages still use `workspace:*` because they are part of this workspace.
+
+## Cloudflare Proof
+
+Deploy the generated apps, then pass each deployed app's generated public URL
+env key into the proof step. A shell-only workspace only needs 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 \
+pnpm cloudflare:proof -- --require-public-urls
+```
+
+## 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 |

package/template-workspace/pnpm-workspace.yaml

@@ -3,7 +3,13 @@ packages:
   - verticals/*
   - packages/*
 
-minimumReleaseAge: 0
+minimumReleaseAge: 1440
+minimumReleaseAgeStrict: true
+minimumReleaseAgeIgnoreMissingTime: false
+minimumReleaseAgeExclude:
+  - '@bleedingdev/modern-js-*'
+trustPolicy: no-downgrade
+trustPolicyIgnoreAfter: 1440
 blockExoticSubdeps: true
 engineStrict: true
 pmOnFail: error