@bleedingdev/modern-js-create 3.2.0-ultramodern.59 → 3.2.0-ultramodern.60

package/dist/types/locale/en.d.ts

@@ -49,6 +49,7 @@ export declare const EN_LOCALE: {
         example9: string;
         example10: string;
         example11: string;
+        example12: string;
         moreInfo: string;
     };
     version: {

package/dist/types/locale/zh.d.ts

@@ -49,6 +49,7 @@ export declare const ZH_LOCALE: {
         example9: string;
         example10: string;
         example11: string;
+        example12: string;
         moreInfo: string;
     };
     version: {

package/package.json

@@ -21,7 +21,7 @@
   "engines": {
     "node": ">=20"
   },
-  "version": "3.2.0-ultramodern.59",
+  "version": "3.2.0-ultramodern.60",
   "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.58"
+    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.2.0-ultramodern.59"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -54,6 +54,6 @@
     "start": "node ./dist/index.js"
   },
   "ultramodern": {
-    "frameworkVersion": "3.2.0-ultramodern.58"
+    "frameworkVersion": "3.2.0-ultramodern.59"
   }
 }

package/template/README.md

@@ -1,18 +1,9 @@
 # UltraModern.js 3.0 Starter
 
-This generated workspace is the Tractor reference SuperApp. It is built around
-one shell and three full-stack Verticals:
-
-| Package | Boundary |
-| --- | --- |
-| `apps/shell-super-app` | Module Federation host, route assembly, topology selection, shell fallback policy |
-| `verticals/explore` | Explore routes, MF exposes, locale JSON, CSS layer, and `/explore-api/effect/explore/*` |
-| `verticals/decide` | Decide routes, MF exposes, locale JSON, CSS layer, and `/decide-api/effect/decide/*` |
-| `verticals/checkout` | Checkout routes, MF exposes, locale JSON, CSS layer, and `/checkout-api/effect/checkout/*` |
-
-Each vertical is a one-package ownership boundary. Its UI, Effect BFF contract,
-generated client, `localisedUrls`, dynamic locale JSON, CSS, MF manifest, and
-Cloudflare Worker output must move together for version-switching proof.
+This generated app is a simple UltraModern.js starting point. It gives one app
+with localized routes, production URL metadata, optional BFF support, Rstest,
+Oxlint, oxfmt, and a local contract check. You can build a useful product here
+without deleting fake product areas, shell packages, or deployment topology.
 
 ## Setup
 
@@ -34,143 +25,80 @@ pnpm dev
 Build the app for production:
 
 ```bash
-pnpm build
-```
-
-Validate the generated Ultramodern preset contract locally:
-
-```bash
-pnpm run ultramodern:check
-```
-
-Run the normal local gates before treating the scaffold as adoption-ready:
-
-```bash
-pnpm run check
-pnpm run build
-pnpm run cloudflare:build
+MODERN_PUBLIC_SITE_URL=https://example.com pnpm build
 ```
 
-The generated preset defaults are opt-out. Disable specific contracts via env vars:
+Preview the production build locally:
 
 ```bash
-MODERN_BASELINE_ENABLE_MF_SSR=false
-MODERN_BASELINE_ENABLE_BFF_REQUEST_ID=false
-MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS=false
+pnpm serve
 ```
 
-The generated starter also includes `.github/workflows/ultramodern-gates.yml`
-and `.github/renovate.json`. The workflow runs
-`pnpm run ultramodern:check` and `pnpm run build` on
-every push and pull request with read-only permissions, commit-pinned actions,
-frozen installs, and StepSecurity audit-mode runner hardening. Renovate is
-configured for dependency dashboard review, one-day release age, grouped
-updates, action digest pinning, and manual approval for major upgrades.
-
-## Vertical Workspaces
-
-Inside an UltraModern workspace, add a full-stack vertical from the workspace
-root. The add flow derives paths, package names, ports, Module Federation names,
-topology entries, overlays, ownership, Effect BFF contracts, and root dev
-scripts:
+Run the local gates before treating the scaffold as ready:
 
 ```bash
-pnpm dlx @modern-js/create catalog --vertical
+pnpm run ultramodern:check
+MODERN_PUBLIC_SITE_URL=https://example.com pnpm run build
 ```
 
-The canonical topology is documented in
-`docs/super-app-rfc-adr/WORKSPACE-0001-micro-vertical-workspace-scaffolding.md`.
-Shell packages own route assembly and topology selection. Verticals own route
-subtrees, degraded UI, Effect BFF contracts, generated clients, and deployment
-evidence. Ordinary workspace packages are limited to tokens, primitives,
-generated clients, or domain-neutral utilities.
+## What You Get
 
-Use a new vertical only when the feature needs its own route subtree owner,
-independent rollout, rollback, Cloudflare/Zephyr evidence, or incident routing.
-Keep code inside an existing vertical when it shares the same product owner,
-fallback behavior, release train, and Effect contract. Do not use a shared
-package for feature composites or workflow state.
+The default app is intentionally monolith-friendly:
 
-Do not add separate service or shared "vertical types". A vertical is the
-full-stack ownership unit. Supporting packages are implementation details and
-should stay ordinary workspace packages unless a real vertical owns the product
-behavior.
-
-The public opinionated entrypoint is `presetUltramodern(...)`. It is the default
-UltraModern.js SuperApp surface for Effect, TanStack, SSR, BFF, and Verticals.
-
-## Module Federation And Effect Ownership
-
-The shell consumes vertical UI through MF manifests and consumes vertical data
-through generated Effect clients exported by the vertical packages:
-
-- Explore exposes header, footer, recommendations, store picker, and route UI.
-- Decide exposes product page and route UI, and may consume Explore or Checkout
-  verticals through declared `verticalRefs`.
-- Checkout exposes cart, checkout, thanks, mini-cart, add-to-cart, and route UI.
-
-The shell owns orchestration and fallback policy. A vertical owns its route-local
-loader/action behavior, degraded UI, `api/effect/index.ts`, shared Effect API
-contract, generated client, and readiness endpoint. Hono remains a compatibility
-lane only when explicitly scaffolded outside the default Tractor workspace.
-
-## I18n And CSS Ownership
-
-Route localization is owned by the package that owns the route. Each app emits
-`src/routes/ultramodern-route-metadata` and passes
-`ultramodernLocalisedUrls` to `@modern-js/plugin-i18n`. Dynamic JSON resources
-are served from `/locales/{{lng}}/{{ns}}.json`; shell rewrites must not replace
-vertical-owned localized URL maps.
-
-CSS federation is recorded in `.modernjs/ultramodern-generated-contract.json`:
+| Area | Starting Point |
+| --- | --- |
+| App routes | Locale-prefixed pages under `src/routes/[lang]` |
+| Copy | English and Czech resources in `config/public/locales` |
+| Styling | App-local CSS, with Tailwind files only when selected |
+| Server logic | Optional BFF entrypoints under `api/` |
+| Tests | Rstest smoke coverage in `tests/` |
+| Agent workflow | Generated `AGENTS.md`, hooks, and local quality gates |
 
-- `packages/shared-design-tokens` owns `ultramodern-shared-tokens` and exports
-  `./tokens.css`.
-- The shell owns shell base and overlay CSS under its app root marker.
-- Each vertical owns one vertical CSS layer and one vertical app root marker.
-- Tailwind CSS v4 is app-local through `@tailwindcss/postcss`.
-- Duplicate base styles are forbidden. SSR first paint requires shared tokens
-  and Modern/Rspack-emitted app CSS.
+Keep feature code in the app while one team owns the workflow, release train,
+and operational behavior. Add ordinary workspace packages for shared tokens,
+small UI primitives, generated clients, or domain-neutral utilities when that
+keeps the app easier to understand.
 
-## Cloudflare And Zephyr Evidence
+## Customize The App
 
-Build all Cloudflare Worker artifacts:
+Start with the generated page and replace the placeholder cards with your first
+real routes, actions, and API calls. Put user-visible text in
+`config/public/locales/<lang>/translation.json`, then render it through
+`react-i18next` or `@modern-js/plugin-i18n/runtime`.
 
-```bash
-MODERN_PUBLIC_SITE_URL=https://shell-super-app.example.test pnpm run cloudflare:build
-```
+Tune the preset in `modern.config.ts`. Production builds require
+`MODERN_PUBLIC_SITE_URL` so canonical and `hreflang` URLs use your deployed
+origin. The local fallback is `http://localhost:8080`.
 
-Validate local or deployed Cloudflare output with the repo harness:
+The generated preset defaults are opt-out. Disable specific contracts via env
+vars when your app needs a softer lane:
 
 ```bash
-node scripts/ultramodern-cloudflare-ssr-validation/validate-cloudflare-ssr.js \
-  --root-dir verticals/checkout \
-  --bff /checkout-api/effect/checkout/readiness \
-  --expect-en "Checkout Vertical" \
-  --match-build-marker \
-  --out .codex/reports/cloudflare-ssr/checkout-local.json
+MODERN_BASELINE_ENABLE_MF_SSR=false
+MODERN_BASELINE_ENABLE_BFF_REQUEST_ID=false
+MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS=false
 ```
 
-After deploying public Workers, run the generated public URL proof:
+## Grow When Needed
 
-```bash
-ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev \
-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 run cloudflare:proof -- --require-public-urls
-```
+Stay in the single app until a boundary has a real owner and operational reason
+to split. A separate package is usually enough when you only need reusable code.
+Consider a larger workspace boundary later when a feature needs independent
+ownership, rollout, rollback, incident routing, or deployment evidence.
 
-Zephyr upload and live switching proof are opt-in evidence workflows. The
-workspace records `zephyr:dependencies` and wires `zephyr-rspack-plugin`, but
-live proof still requires public manifest, runtime, and API URLs plus Zephyr
-credentials. Without those values, only dry-run Zephyr evidence can be claimed.
+The public opinionated entrypoint is `presetUltramodern(...)`. It keeps Effect,
+TanStack, SSR, BFF, i18n, and quality gates available without requiring a
+distributed app layout on day one.
 
-Preview the production build locally:
+## Generated Automation
 
-```bash
-pnpm serve
-```
+The generated starter includes `.github/workflows/ultramodern-gates.yml` and
+`.github/renovate.json` for full app projects. The workflow runs
+`pnpm run ultramodern:check` and `pnpm run build` on every push and pull request
+with read-only permissions, commit-pinned actions, frozen installs, and
+StepSecurity audit-mode runner hardening. Renovate is configured for dependency
+dashboard review, one-day release age, grouped updates, action digest pinning,
+and manual approval for major upgrades.
 
 For more information, see the
 [UltraModern.js guide](https://bleedingdev.github.io/ultramodern.js/guides/get-started/ultramodern.html)

package/template/config/public/locales/cs/translation.json

@@ -5,27 +5,27 @@
     },
     "cards": {
       "bff": {
-        "body": "Pouzivej Effect jako hlavni BFF cestu, Hono nech jako explicitni zalozni volbu.",
+        "body": "Pridej serverovou logiku, kdyz route potrebuje typovana data nebo mutace.",
         "title": "BFF + Effect"
       },
       "config": {
-        "body": "Upravuj vygenerovane vychozi hodnoty v modern.config.ts.",
+        "body": "Upravuj vychozi hodnoty v modern.config.ts podle rustu aplikace.",
         "title": "Konfigurace presetUltramodern"
       },
       "gates": {
-        "body": "Starter obsahuje PR workflow pro ultramodern:check a build.",
+        "body": "Pred releasem spust ultramodern:check, testy, typecheck, lint a build.",
         "title": "Ultramodern kontroly"
       },
       "guide": {
-        "body": "Projdi si verejny preset pripraveny pro MV, TanStack a Effect.",
+        "body": "Zacni jednou aplikaci a pridej routy, API nebo balicky az kdyz pomuzou.",
         "title": "UltraModern.js pruvodce"
       }
     },
     "description": {
-      "afterConfig": ", udrzuj",
-      "afterPreset": "profil. Zacni v",
-      "end": "zelene a lad vygenerovany preset jen tam, kde aplikace potrebuje mekci cestu.",
-      "intro": "Tento starter prinasi verejny"
+      "afterConfig": "podle rustu aplikace a udrzuj",
+      "afterPreset": "profilem. Lad",
+      "end": "zelene pri pridavani rout, API a workspace balicku.",
+      "intro": "Zacni s verejnym"
     },
     "language": {
       "cs": "Cestina",
@@ -33,7 +33,7 @@
       "switcher": "Jazyk"
     },
     "logoAlt": "Logo UltraModern.js",
-    "name": "presetUltramodern",
-    "title": "UltraModern.js 3.0"
+    "name": "Jednoduchy starter aplikace",
+    "title": "UltraModern.js Starter"
   }
 }

package/template/config/public/locales/en/translation.json

@@ -5,27 +5,27 @@
     },
     "cards": {
       "bff": {
-        "body": "Keep Effect as the preferred BFF lane while Hono stays an explicit fallback.",
+        "body": "Add server logic when a route needs typed data or mutation handling.",
         "title": "BFF + Effect"
       },
       "config": {
-        "body": "Tune the generated defaults in modern.config.ts.",
+        "body": "Tune generated defaults in modern.config.ts as the app grows.",
         "title": "Configure presetUltramodern"
       },
       "gates": {
-        "body": "The starter includes a PR workflow for ultramodern:check and build.",
+        "body": "Run ultramodern:check, tests, typecheck, lint, and build before release.",
         "title": "Ultramodern Gates"
       },
       "guide": {
-        "body": "Review the MV-first, TanStack-ready, Effect-ready public preset.",
+        "body": "Start with one app, then add routes, APIs, and packages when they help.",
         "title": "UltraModern.js Guide"
       }
     },
     "description": {
-      "afterConfig": ", keep",
-      "afterPreset": "profile. Start in",
-      "end": "green, and tune the generated preset only where your app needs a softer lane.",
-      "intro": "This starter ships the public"
+      "afterConfig": "as the app grows, and keep",
+      "afterPreset": "profile. Tune",
+      "end": "green while you add routes, APIs, and workspace packages.",
+      "intro": "Start from the public"
     },
     "language": {
       "cs": "Czech",
@@ -33,7 +33,7 @@
       "switcher": "Language"
     },
     "logoAlt": "UltraModern.js Logo",
-    "name": "presetUltramodern",
-    "title": "UltraModern.js 3.0"
+    "name": "Simple app starter",
+    "title": "UltraModern.js Starter"
   }
 }

package/template/src/routes/[lang]/page.tsx.handlebars

@@ -123,12 +123,14 @@ const Index = () => {
         <p className="description{{#if enableTailwind}} text-emerald-700 font-semibold{{/if}}">
           {t('home.description.intro')} <code className="code">presetUltramodern(...)</code>{' '}
           {/* i18n-ignore technical token */}
-          {t('home.description.afterPreset')}
+          {t('home.description.afterPreset')}{' '}
           <code className="code">modern.config.ts</code>
           {/* i18n-ignore technical token */}
-          {t('home.description.afterConfig')}
+          {' '}
+          {t('home.description.afterConfig')}{' '}
           <code className="code">pnpm run ultramodern:check</code>
           {/* i18n-ignore technical token */}
+          {' '}
           {t('home.description.end')}
         </p>
 {{#if useEffectBff}}

package/template-workspace/AGENTS.md

@@ -1,6 +1,8 @@
 # UltraModern Agent Contract
 
-This workspace is generated as an agent-ready UltraModern.js SuperApp. Agents should treat the files under `.agents/skills` as local project instructions, not optional reading.
+This workspace is generated as an agent-ready UltraModern.js SuperApp shell.
+Agents should treat the files under `.agents/skills` as local project
+instructions, not optional reading.
 
 ## Quality Gates
 
@@ -13,7 +15,14 @@ This workspace is generated as an agent-ready UltraModern.js SuperApp. Agents sh
 
 ## Localized Routes
 
-Generated apps keep locale-prefixed entry routes under `src/routes/[lang]`, static language links, and canonical plus `hreflang` metadata. Runtime i18n is not enabled in the starter because the current React 19 + Module Federation streaming SSR stack must render predictably first. Production builds fail unless `MODERN_PUBLIC_SITE_URL` is set per deployed app, so canonical URLs always use the production origin.
+Generated apps keep locale-prefixed entry routes under `src/routes/[lang]`,
+static language links, and canonical plus `hreflang` metadata. A new workspace
+starts shell-only; `create <domain> --vertical` adds route-owned metadata,
+localized resources, and Effect BFF surfaces for that domain. Runtime i18n is
+not enabled in the starter because the current React 19 + Module Federation
+streaming SSR stack must render predictably first. Production builds fail unless
+`MODERN_PUBLIC_SITE_URL` is set per deployed app, so canonical URLs always use
+the production origin.
 
 ## Required Skill Baseline
 
@@ -52,9 +61,13 @@ Agents may read files under `repos/` to understand upstream patterns, APIs, and
 ## Project Priorities
 
 - Keep `presetUltramodern` as the single preset.
-- Prefer Effect for BFF/service code.
+- Keep the initial workspace shell-only unless a user explicitly asks for a
+  starter vertical.
+- Use `create <domain> --vertical` as the growth path for real business
+  MicroVerticals.
+- Prefer Effect for BFF code.
 - Prefer TanStack Router for app routing.
-- Keep design-system code as a normal Micro Frontend or shared package, not a special core path.
+- Keep UI-kit or design-system code as ordinary vertical or shared package code, not a special core path.
 - Keep generated packages explicit and publishable: stable `exports`, correct declarations, small public APIs, and clear ownership metadata.
 - Do not add migration tooling or codemods unless the project owner explicitly asks for migration work.
 

package/template-workspace/README.md.handlebars

@@ -3,25 +3,28 @@
 Generated UltraModern SuperApp workspace.
 
 This workspace keeps `presetUltramodern(...)` as the single public
-UltraModern.js 3.0 SuperApp surface and scaffolds the canonical Micro Vertical
-starter topology:
-
-- `apps/shell-super-app` owns shell route assembly and federated manifest wiring.
-- `verticals/commerce` owns the commerce vertical, its
-  browser-safe Module Federation exposes, and its Effect BFF/API surface.
-- `verticals/identity` owns the identity vertical, its
-  browser-safe Module Federation exposes, and its Effect BFF/API surface.
-- `verticals/design-system` owns the design-system vertical.
-- `packages/shared-*` provide placeholders for cross-workspace contracts.
-
-Default vertical APIs are owned by the vertical package.
-Each full-stack vertical keeps its `api/effect/index.ts` handlers next to its
-`shared/effect/api.ts` contract and `src/effect/*-client.ts` typed client
-surface. The Module Federation config exposes only browser-safe Route and
-Widget modules; server handlers and Effect client/contract modules stay out of
-browser verticals.
-
-Run the scaffold validator before adding business code:
+UltraModern.js 3.0 SuperApp surface and starts with an explicit shell:
+
+- `apps/shell-super-app` owns shell route assembly, Module Federation host
+  wiring, shared SSR/i18n runtime setup, and the boundary debugger.
+- `packages/shared-*` provide placeholders for cross-workspace contracts,
+  design tokens, and Effect API sharing.
+- `verticals/*` is intentionally empty until a real business domain is added.
+
+Add a full-stack MicroVertical when the product needs one:
+
+```bash
+pnpm create modern@latest transportation --vertical
+pnpm create modern@latest payments --vertical
+```
+
+Each added vertical owns its UI/routes, browser-safe Module Federation exposes,
+localized route metadata, CSS prefix, Effect BFF handlers, local API contract,
+and typed client surface. Server handlers and Effect client/contract modules
+stay out of browser exposes.
+
+Run the scaffold validator before adding business code and after every
+`--vertical` mutation:
 
 ```bash
 mise install

package/template-workspace/scripts/assert-mf-types.mjs

@@ -1,44 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-const root = process.cwd();
-const defaultAppDirs = [
-  'verticals/commerce',
-  'verticals/identity',
-  'verticals/design-system',
-];
-
-const candidateDirs = process.argv.slice(2);
-const appDirs = candidateDirs.length
-  ? candidateDirs
-  : fs.existsSync(path.join(root, 'module-federation.config.ts'))
-    ? ['.']
-    : defaultAppDirs;
-
-for (const appDir of appDirs) {
-  const configPath = path.join(root, appDir, 'module-federation.config.ts');
-  if (!fs.existsSync(configPath)) {
-    throw new Error(
-      `Missing Module Federation config: ${path.relative(root, configPath)}`,
-    );
-  }
-
-  const config = fs.readFileSync(configPath, 'utf-8');
-  if (!config.includes('exposes:') || config.includes('dts: false')) {
-    continue;
-  }
-
-  const typesArchivePath = path.join(root, appDir, 'dist/@mf-types.zip');
-  if (!fs.existsSync(typesArchivePath)) {
-    throw new Error(
-      `Missing Module Federation DTS archive: ${path.relative(root, typesArchivePath)}`,
-    );
-  }
-
-  const stats = fs.statSync(typesArchivePath);
-  if (stats.size === 0) {
-    throw new Error(
-      `Empty Module Federation DTS archive: ${path.relative(root, typesArchivePath)}`,
-    );
-  }
-}