UltraModern.js Create

The BleedingDev create package has one supported generated product: an UltraModern SuperApp workspace.

pnpm dlx @bleedingdev/modern-js-create my-workspace

The supported pnpm command contract is the scoped package specifier above: pnpm dlx @bleedingdev/modern-js-create <target>. Do not shorten it to pnpm dlx modern-js-create; there is no unscoped modern-js-create npm package. Release proof runs this scoped form from a temporary pnpm store/cache so it cannot pass because of a local link cache.

To initialize the empty directory you are already in, pass . explicitly:

pnpm dlx @bleedingdev/modern-js-create .

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 a real domain is added with --vertical.
• packages/shared-* placeholders for shared contracts, tokens, and Effect API support.
• .modernjs/ultramodern-generated-contract.json with Module Federation, Effect, i18n, federated CSS, Cloudflare, route publicness, generated public-surface, and Zephyr dependency metadata.

Validate the generated workspace before making application changes:

cd my-workspace
mise install
pnpm install
pnpm check
pnpm build

The generated toolchain baseline is Node >=26 with pnpm 11+. packageManager, .mise.toml, generated validation, and CI should all agree on that baseline; do not reintroduce Corepack or older pnpm aliases.

Generated CI does not call the local aggregate. It runs format, lint, typecheck, skills, i18n boundary validation, contract validation, and build as separate matrix jobs so failures are isolated and parallelizable. Generated lefthook config runs separate format and lint-fix commands on pre-commit, then runs the read-only primitive gates in parallel on pre-push.

For local monorepo dependency testing, add --workspace:

pnpm dlx @bleedingdev/modern-js-create my-workspace --workspace

For package-source validation outside the monorepo, pass explicit --ultramodern-package-* options.

Vertical Workspace Recipes

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.

pnpm dlx @bleedingdev/modern-js-create catalog --vertical

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 |

SuperApp Architecture Contracts

The generated shell owns route assembly and policy. Each vertical added with --vertical owns its route subtree, Module Federation exposes, Effect BFF contract, generated client, localisedUrls, locale JSON, CSS layer, and Cloudflare Worker output. The shell consumes vertical UI through Module Federation manifests and vertical APIs through generated Effect clients exported by the vertical packages.

Route metadata is route-owned and colocated in src/routes/**/route.meta.ts. The scaffold regenerates src/routes/ultramodern-route-metadata.ts as a compatibility manifest for Modern.js config, i18n, public head, and public surface contracts; authors should not hand-maintain it. Locale JSON is served from /locales/{{lng}}/{{ns}}.json; Czech and English routes are generated from the route owner, not from shell rewrites.

Routes default to privateByDefault: true and publicnessDefault: private-app-screen. Public web artifacts are build/deploy outputs generated by scripts/generate-public-surface-assets.mjs into dist/public and .output/public, not source files under config/public. Generated public files use only explicit public && indexable route metadata, so private app screens publish only a disallowing robots.txt by default. JSON-LD is not inferred from route titles, descriptions, localized paths, app names, BFF APIs, or Module Federation metadata. To publish structured data, author jsonLd explicitly in route metadata for a public && indexable route; generated apps provide src/routes/ultramodern-jsonld.ts helpers for WebPage, WebApplication, SoftwareApplication, BreadcrumbList, FAQPage, and Organization, while raw JSON-LD remains possible for other schema types.

Dynamic public routes can expand sitemap entries through route-owned, Node-safe ESM providers, normally route.sitemap.mjs beside the route metadata. The public-surface generator discovers those providers for dynamic public routes and still honors explicit routes.publicSurface.contentSources entries in the generated compatibility manifest. Providers may export entries, entries(), or a default entries/loader returning sitemap entries; draft entries and indexable: false entries are omitted.

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.

Public URL Environment Variables

Generated apps must not bake absolute http://localhost:<port> URLs into asset configuration. Public URL and asset prefix environment variables have distinct roles, and stale aliases should not be carried forward when regenerating or updating workspaces.

| Variable | Role | Feeds | | --- | --- | --- | | MODERN_PUBLIC_SITE_URL | Canonical site origin for public SEO output only | Canonical, hreflang, sitemap <loc>, robots Sitemap: | | MODERN_ASSET_PREFIX | Preferred JS/CSS/static asset prefix | Modern/Rspack-emitted asset URLs | | ULTRAMODERN_ASSET_PREFIX | UltraModern compatibility asset prefix | Modern/Rspack-emitted asset URLs when MODERN_ASSET_PREFIX is unset | | ULTRAMODERN_PUBLIC_URL_<APP_ID> | Per-app deployment/proof URL | Cloudflare proof inputs and Module Federation remote URLs |

Asset URLs use this precedence: MODERN_ASSET_PREFIX → ULTRAMODERN_ASSET_PREFIX → origin-relative /. MODERN_PUBLIC_SITE_URL is canonical/SEO-only and must not be used as an asset-prefix fallback. SEO output uses MODERN_PUBLIC_SITE_URL; if it is unset, generated local and preview outputs remain non-public until deployment proof provides explicit public URLs.

Without public URLs configured, asset paths are origin-relative (/), and the dev server uses dev.assetPrefix: '/' — so apps work through tunnels and reverse proxies (ngrok, cloudflared) without triggering Chrome's Local Network Access prompt or mixed-content errors. Shell-only workspaces can set MODERN_PUBLIC_SITE_URL for SEO output without changing where assets load from.

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. The proof script reads the generated contract and checks the Cloudflare Worker surface, including public-route sitemap/robots consistency, preview noindex behavior, unknown-route status, asset headers, byte budgets, and public sourcemap exposure. 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:

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 primitive gates 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 the matching primitive gate (pnpm lint, pnpm typecheck, pnpm i18n:boundaries, pnpm contract:check) before pnpm build; fix the owning failure 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 |

Modern.js Documentation

• English Documentation
• 中文文档

License

Modern.js is MIT licensed.