@bleedingdev/modern-js-create 3.2.0-ultramodern.9 → 3.2.0-ultramodern.91

package/README.md

@@ -12,85 +12,122 @@
 
 Please follow [Quick Start](https://modernjs.dev/en/guides/get-started/quick-start) to get started with Modern.js.
 
-For UltraModern.js, use the BleedingDev create package. It defaults to the
-canonical SuperApp workspace and published BleedingDev package aliases:
+For UltraModern.js, use the BleedingDev create package. It defaults to a
+production-ready single app with `presetUltramodern(...)`, TanStack Router,
+Tailwind CSS v4, i18n, Effect BFF, generated quality gates, and published
+BleedingDev package aliases:
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create my-super-app
+pnpm dlx @bleedingdev/modern-js-create my-app
 ```
 
-### Router Template
+To initialize the empty directory you are already in, pass `.` explicitly:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create .
+```
 
-You can scaffold a TanStack Router first template:
+The default is the full UltraModern single-app setup. Create a SuperApp
+workspace explicitly when you need independently owned verticals:
 
 ```bash
-npx @modern-js/create my-app --router tanstack
+pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
 ```
 
-### Tailwind Template
+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/*` 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.
 
-You can scaffold Tailwind CSS v4 setup (PostCSS + starter utility classes):
+Validate the generated workspace before making application changes:
 
 ```bash
-npx @modern-js/create my-app --tailwind
+cd my-super-app
+mise install
+pnpm install
+pnpm check
+pnpm build
 ```
 
-You can combine both options:
+### Router Template
+
+TanStack Router is generated by default. Choose React Router only as an explicit
+compatibility lane:
 
 ```bash
-npx @modern-js/create my-app --router tanstack --tailwind
+pnpm dlx @bleedingdev/modern-js-create my-app --router react-router
 ```
 
-### BFF Runtime Template
+### Tailwind Template
 
-You can scaffold BFF APIs with the current default runtime:
+Tailwind CSS v4 setup is generated by default. Disable it explicitly when you
+need a plain CSS starter:
 
 ```bash
-npx @modern-js/create my-app --bff
+pnpm dlx @bleedingdev/modern-js-create my-app --no-tailwind
 ```
 
-You can explicitly scaffold Effect HttpApi runtime for BFF:
+TanStack Router and Tailwind CSS work together without extra flags:
 
 ```bash
-npx @modern-js/create my-app --bff-runtime effect
+pnpm dlx @bleedingdev/modern-js-create my-app
+```
+
+### BFF Runtime Template
+
+UltraModern app scaffolds include Effect HttpApi BFF by default:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-app
 ```
 
 To scaffold Hono runtime explicitly:
 
 ```bash
-npx @modern-js/create my-app --bff-runtime hono
+pnpm dlx @bleedingdev/modern-js-create my-app --bff-runtime hono
 ```
 
 Generated starters expose `presetUltramodern(...)` as the public opinionated
 config wrapper when you want the full Ultramodern setup surface in
 `modern.config.ts`.
 
-You can combine TanStack Router + Tailwind + Effect BFF in one command:
+TanStack Router, default Tailwind, and Effect BFF are included without extra
+flags. For local monorepo dependency testing, add `--workspace`:
 
 ```bash
-npx @modern-js/create my-app --router tanstack --tailwind --bff-runtime effect
+pnpm dlx @bleedingdev/modern-js-create my-app --workspace
 ```
 
-### Micro Vertical Workspace Recipes
+### Vertical Workspace Recipes
 
-Use the existing create flags to scaffold packages inside a Micro Vertical
-workspace. The shell and remotes use TanStack Router; services use Effect by
-default, with Hono kept as an explicit compatibility lane.
+Use the workspace add flow from the UltraModern workspace root. It derives the
+package path, package name, port, Module Federation name, topology entry, local
+overlay, ownership entry, Effect BFF surface, and root `dev:*` script from the
+requested vertical name.
 
 ```bash
-npx @modern-js/create apps/shell --router tanstack --tailwind --workspace --sub
-npx @modern-js/create apps/remotes/catalog --router tanstack --tailwind --workspace --sub
-npx @modern-js/create apps/remotes/design-system --router tanstack --tailwind --workspace --sub
-npx @modern-js/create services/catalog-api --bff-runtime effect --workspace --sub
-npx @modern-js/create services/legacy-api --bff-runtime hono --workspace --sub
+pnpm dlx @bleedingdev/modern-js-create catalog --vertical
 ```
 
-When a design system needs independent deployment, treat it as a horizontal
-Module Federation remote with the same topology, trust, SSR, compatibility, and
-fallback expectations as feature remotes. Otherwise shared packages should be
-regular workspace packages for tokens, primitives, generated clients, or
-domain-neutral utilities. Keep feature composites and workflow logic owned by a
-shell, remote, or service package.
+Use this decision table before adding a vertical:
+
+| Need | Keep inside current vertical | Create a new vertical |
+| --- | --- | --- |
+| Route or widget changes with the same product owner, release train, and fallback behavior | Yes | No |
+| Route subtree needs independent rollout, rollback, or incident ownership | No | `--vertical` |
+| UI and Effect BFF must version, deploy, and roll back together | No | `--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 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`
@@ -101,13 +138,93 @@ 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.
 
+### SuperApp Architecture Contracts
+
+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
+`ultramodernLocalisedUrls` into `@modern-js/plugin-i18n`. Locale JSON is served
+from `/locales/{{lng}}/{{ns}}.json`; Czech and English routes are generated from
+the route owner, not from shell rewrites.
+
+CSS federation is explicit:
+
+- `packages/shared-design-tokens` exports `./tokens.css` and owns
+  `ultramodern-shared-tokens`.
+- The shell owns shell base and overlay CSS only.
+- Verticals own their vertical CSS layer and `[data-app-id="<vertical>"]`
+  root marker.
+- Tailwind CSS v4 is configured per app through `@tailwindcss/postcss`.
+- Duplicate base styles are forbidden; SSR first paint depends on shared token
+  CSS plus Modern/Rspack-emitted app CSS.
+- Apps should not inject remote `async-index.css` paths, hardcode remote
+  stylesheet links, or disable filename hashing to make CSS URLs predictable.
+  UltraModern SSR resolves federated CSS from build output and MF manifests so
+  generated shells and demos can keep normal hashed assets.
+
+Version switching evidence must keep UI, Effect API, CSS, i18n JSON, and MF
+manifest markers in lockstep for the same vertical version.
+
+### Cloudflare And Zephyr Proof
+
+Each generated workspace app has:
+
+- `cloudflare:build`, `cloudflare:deploy`, `cloudflare:preview`, and
+  `cloudflare:proof` scripts.
+- Cloudflare metadata in `.modernjs/ultramodern-generated-contract.json`.
+- `zephyr:dependencies` for any consumed verticals.
+- `zephyr-rspack-plugin` wired through the generated Modern.js Rspack bridge.
+
+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
+```
+
+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
 
 When testing unreleased Modern.js packages from a local monorepo checkout, use
 workspace protocol dependencies:
 
 ```bash
-npx @modern-js/create my-app --router tanstack --bff-runtime effect --workspace
+pnpm dlx @bleedingdev/modern-js-create my-app --workspace
+```
+
+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 my-super-app --ultramodern-workspace --ultramodern-package-source workspace
+cd my-super-app
+pnpm install
+pnpm check
 ```
 
 ## Documentation