region	{{ k }}
{{ r.region }}	{{ r[k] }}

`, a `v-if="loading"` placeholder, the legacy `client-skeleton-*` attributes). Every mono element has a `pending` prop drawn by the optional peer `@aejkatappaja/phantom-ui`: install it in the Host and, in an SSR app, the light components of a page pend on their own until their first data is in (tables until the grid has loaded, selects until their source has a page; buttons / inputs never flash). For a busy state of your own, bind it: `:pending="store.saving"` or `:pending.prop="{ active, count: 6 }"`. See [Addons → Skeleton](/addons/skeleton). ::: ### N6. Dev-only knobs live in `nuxt.config.ts` > **When:** setting a port or the client env prefix. > **Do:** use `devServer.port`, and put Vite-only options under the `vite` key (Rule 7). > **Don't:** read `PORT` from `.env`, or create a `vite.config.ts` to hold them (Rule N1). ```ts export default defineNuxtConfig({ devServer: { port: 2020 }, vite: { envPrefix: ['VITE_', 'MONO_'] }, // only these prefixes reach client code }) ``` ## Before you finish A quick self-check against the always-rules before you call a change done: - [ ] You read the section matching this app's `type` — and applied **only** that one (Vue / Nuxt). - [ ] The `mono-*` build matches the language: light in a Vue app, shadow in a Nuxt host (Rules 11, V5, N5). - [ ] New files landed in the right source root — `src/` in Vue (V2), `app/` in Nuxt (N2). - [ ] All data access goes through `@mono-lit/utility/fetching` — no external HTTP lib (Rule 12). - [ ] A detail / single-row read **reuses an existing DataSource** (`source.store().load({ take: 1 })` when it's bound to a component) instead of a second fetcher; never `store().byKey()` (Rule 12). - [ ] Every new store has a **unique export name and `defineStore` key** (app-suffixed) (Rule 8). - [ ] Nothing under `.mono/apps/` or any generated file (`*.d.ts`, `.nuxt/`, `.mono/tsconfig.json`, `odata/DTO/`) was hand-edited (Rules 3, 4, V3, N3). - [ ] OData types are **generated + mapped** with `MonoOdataMapTypes`, not hand-written (Rule 13). - [ ] Variables/functions use consistent leading prefixes and handlers take one typed object — `openModal({ item }: { item: T })` (Rule 6). - [ ] Typed data has its shape in a `.d.ts`; static data lives in `datas/` (Rules 16, 9). - [ ] Cross-app / `datas`·`types`·`odata` imports use the `@app-name` alias (Rule 2). - [ ] UI starts from `@mono-lit/helper/ui`; secrets live in env with the right prefix (Rules 14, 7). - [ ] If the Host shell looks unstyled (layout/sidebar lose their utility classes while `mono-*` components still render), `uno.config.ts` scans `.mono/apps` via an **absolute** `content.filesystem` base, not a relative glob (Rule 1). - [ ] You paused to **ask** before touching infra (the build config, aliases, `mono.config.ts` `extends`/`apps`). - [ ] If `skill` is configured in `mono.config.ts` and the work was meaningful, the session was saved with `mono skills save` and the `repoPath` reported (Rule 17). ## Host template > **When:** you're working in the **Host**. > **Do:** own the shared shell — `pages` (Login/Logout), `layouts` (Sidebar/Navbar), Middleware, and the **theme** (Mono/Material + color). > **Don't:** bury a Remote's module-specific logic in the Host. The Host owns the **shell** every Remote reuses — see [Getting Started](../repo/getting-started). All Common Rules above apply here too — **General**, plus [Vue](#common-rules-vue) or [Nuxt](#common-rules-nuxt) depending on this Host's `type`. - **Owns:** Login / Logout pages, layouts (Sidebar, Navbar), Middleware — the generic pieces a Remote should never rebuild. - **Owns the theme — and is the *only* app that does.** The Host is the single place that imports the theme CSS (`@mono-lit/helper/index.css`, plus `@mono-lit/helper/ui/theme/.css` only if Material is used) and sets the active **theme** (Mono / Material) and **theme color** via the theming API (`applyTheme` / `applyFlavor`). Theme/color apply as classes on a root element (`` / ``), so they cascade into every Remote automatically — a Remote inherits the Host's theme without importing or applying anything. See [Theme](/ui/theme). - **Exposes to Remotes** via the three Host ↔ Remote links (Rule 1) and `mono.config.ts` (Rule 5): its shared pages/components/stores and the merged cookie/JWT/API/menu config. - **Keep out of the Host:** feature logic that belongs to one Remote's module — build that in the Remote. #### When the Host is a Nuxt app A Host can be a **Nuxt** app instead of Vue + Vite (`type: 'nuxt'` in `mono.config.ts`). It owns the same shell and theme — only the language-level wiring differs, and that is now covered in full by **[Common Rules: Nuxt](#common-rules-nuxt)**: `nuxt.config.ts` as the core (N1), source under `app/` (N2), registration via `app/plugins/mono.ts` (N4), and the shadow-DOM component build for the server-rendered shell (N5). Nothing about the Host's **role** changes: it still owns Login/Logout, layouts, Middleware, and the theme. [Setup](../repo/setup) has the full config walkthrough. Starter apps (in the `mono-lit/templates` monorepo): Vue · Nuxt ## Remote template > **When:** you're working in a **Remote**. > **Do:** add your own modules under `src/`, and register pages in `mono.config.ts` `menu` to appear in the Host nav. > **Don't:** re-create Login / Logout / layouts / Middleware, or manage the theme — the Host already provides them. A Remote only **adds its own modules** and consumes the Host's shell — see [Getting Started](../repo/getting-started). All Common Rules above apply here too — **General** plus [Vue](#common-rules-vue). Under the standard a Remote **matches its Host's framework** — this Vue template is the Remote of a **Vue Host**. - **Adds:** its feature pages, components, stores under its own `src/` (auto-imported per Rule V1). - **Surfaces in the Host:** add a `menu` entry in `mono.config.ts` (Rule 5) so the module shows in the Host's navigation; ask the user whether a new page should be deployable yet (Rule 12). - **Don't rebuild the shell:** Login, Logout, Sidebar, Navbar, Middleware and layouts come from the Host — just use them. - **Don't manage the theme.** Don't import the theme CSS (`@mono-lit/helper/index.css`, `@mono-lit/helper/ui/theme/.css`) and don't call `applyTheme` / `applyFlavor`. The **Host** owns and applies the theme globally; a Remote just uses the `mono-*` components and inherits the active theme/color. See [Theme](/ui/theme). #### When the host is a Nuxt app ::: warning Hybrid pairing — possible, but at your own risk A Vue Remote under a Nuxt Host is **outside the same-framework standard**. The combination still boots — mono's compat layer (Rule V7) rewrites the host's Nuxt code for the Remote's Vite build — but the seams it papers over (SSR, layouts, routing, state) stay your risk. Prefer a Nuxt Remote for a Nuxt Host; see [Setup](../repo/setup). ::: A Vue Remote stays a Vue + Vite app even when its Host is **Nuxt** — you keep reading [Common Rules: Vue](#common-rules-vue), you write the same `src/` modules, and your day-to-day code is unchanged. **Do not switch to the Nuxt section, and do not switch to the shadow component build** (Rule V5) — the Host's `type` is not yours. Only `vite.config.ts` infra differs, and that is **Rule V7**: `apps[].type: 'nuxt'` makes `mono prepare` resolve `@mono-host/*` to the host's `app/*` (Rule 2), and the build adds the Nuxt-compat helpers `mono.nuxt().hostResolver()` / `.extendRoute()` alongside the same type-driven `mono.ecosystem(...)` discovery. See [Setup](../repo/setup) for the exact config. Starter: the `vue-remote` app in --- URL: "https://mono-libs.netlify.app/example/layout-rule" LLMS_URL: "https://mono-libs.netlify.app/example/layout-rule.md" layout: false title: "Layout Rule Example" description: "The house layout rule — the table shape and the form shape — rebuilt end to end with mono components and static data, with every region labelled so the skeleton is inspectable." --- --- URL: "https://mono-libs.netlify.app/example/odoo" LLMS_URL: "https://mono-libs.netlify.app/example/odoo.md" layout: false title: "Odoo Sales Order Example" description: "A full-page Odoo-style sales-order screen built with mono UI — a data table, form fields and actions — demonstrating a complete CRUD-style business form." --- --- URL: "https://mono-libs.netlify.app/lith/cli-typescript" LLMS_URL: "https://mono-libs.netlify.app/lith/cli-typescript.md" --- # CLI & TypeScript The `mono` commands treat a `path` app exactly like every other consumer: `mono sync` has nothing to clone for it, `mono env` loads its `.env.` like a clone's, and `mono prepare` writes its alias into `.mono/tsconfig.json` — pointing outside the project, which is the one thing TypeScript needs a word about. ## `mono sync` Every app is looked at before any network call: ``` ==> Check esw-reports (EJI-ICT/esw-reports@mono) ← a url-only app: cloned as always 🔗 esw-master: linked to ../esw-master — nothing to clone. 🔗 esw-project: linked to ../esw-project — nothing to clone. ===== Summary ===== ✅ Success (1): • esw-reports (EJI-ICT/esw-reports@mono @ 3c5d768) via git ❌ Failed (0): 🔗 Linked (2): • esw-master (../esw-master, read in place) • esw-project (../esw-project, read in place) ``` - A `path` whose directory is absent **and** has a `url` is synced from GitHub with a warning (`⚠️ esw-project: path '../esw-project' not found (looked in …) — syncing from GitHub instead.`). This is the lifted-out-of-the-lith case. - A `path` whose directory is absent and has **no** `url` fails that app (exit code 1) — there is nothing to fall back to. - An entry with neither `url` nor `path` is rejected while parsing `apps[]`. - Pruning is unchanged: `.mono/apps/` not named in `apps[]` is removed; a `path` app's name still protects a stale clone of it, which is shadowed and reported, never deleted. Only `url` apps contribute commit-cache and access-cache keys. ## `mono env` `mono env -e .env.dev -- vite` loads the root `.env.dev`, then every federated app's `.env.dev` — clones **and** `path` siblings, the same list every other command sees: ``` [mono-env] Loaded root env: .env.dev [mono-env] Loaded app:esw-master env: ../esw-master/.env.dev [mono-env] Loaded app:esw-project env: ../esw-project/.env.dev [mono-env] Apps: esw-master, esw-project ``` `-a ` picks one app by name whether it is a clone or a sibling; `MONO_APP_DIR` is that app's real directory. (The resolver lives in the built `config-node.js`; run straight from the repo's `bin/`, the script falls back to listing `.mono/apps` as it always did.) ## `mono prepare` `.mono/tsconfig.json` maps every alias to the directory Vite reads, so for a sibling it now points **outside** the project: ```json { "compilerOptions": { "paths": { "@esw-host/*": ["../src/*"], "@esw-host-root/*": ["../*"], "@esw-project/*": ["../../esw-project/src/*"], "@esw-project-root/*": ["../../esw-project/*"] } } } ``` ### `rootDir` TypeScript refuses a path mapping that escapes `compilerOptions.rootDir` ("File … is not under 'rootDir'") for every importer of that alias. `mono prepare` will not edit the option — only the project knows whether `"."` was deliberate — it warns once and lists the keys: ``` [mono] tsconfig.json sets rootDir "." but @esw-project/*, @esw-project-root/* map outside the project (apps[].path siblings). Remove rootDir, or set it to the folder that contains every sibling (e.g. "../"). ``` **Recommendation: drop `rootDir`.** A Vite / vue-tsc project has `noEmit: true`, so `rootDir` buys nothing. If a project insists on one, `"../"` (the `apps/` folder) is the value that contains every sibling. `runMonoPrepare()` returns the keys as `outsideProject` for tooling. ### Each sibling runs its own prepare `mono prepare` wires the generated tsconfig into **clones** only (`.mono/apps//tsconfig.json` gains `extends: ["../../tsconfig.json"]`). It never writes into a `path` sibling's `tsconfig.json`: that is someone's real repository, the edit would dirty their tree with a path only valid on this machine, and the host's `paths` would then resolve inside a project with its own `rootDir`. Instead each sibling carries its own `mono.config.ts` and runs its own `mono prepare` — its `postinstall` already does — which writes the same map from its point of view (`@esw-host/*` → `../../esw-host/src/*` in `apps/esw-project/.mono/tsconfig.json`). A root `pnpm install` runs every workspace package's `postinstall`, so the whole lith is prepared in one go. If a sibling has **not** run it yet, its `tsconfig.json` still extends a `./.mono/tsconfig.json` that is missing — Vite's esbuild plugin then fails that sibling's SFCs with "Tsconfig not found". `mono prepare` in the host detects that and says so: ``` [mono] esw-project: tsconfig.json extends ./.mono/tsconfig.json but the file is missing — run `mono prepare` in that app. ``` ### `defineProps()` across siblings `@vue/compiler-sfc` resolves the type-only imports in `defineProps()` through the **nearest** `tsconfig.json`'s `paths` — for `apps/esw-project/src/x.vue` that is esw-project's own tsconfig, never the host's, and Vite's `resolve.alias` is invisible to it. So a sibling's SFC importing `@esw-host/types/…` works when: 1. the sibling declares `esw-host` in **its own** `apps[]` (it does — remotes list the host back), and 2. the sibling has run `mono prepare` (see above). ### `tsconfig.build.json` A build tsconfig that redefines `paths` (to add `@/*`, say) replaces the whole inherited map, so its mono entries have to name the siblings too: ```json { "extends": "./tsconfig.json", "compilerOptions": { "paths": { "@/*": ["./src/*"], "@esw-project/*": ["../esw-project/src/*"], "@esw-project-root/*": ["../esw-project/*"] } } } ``` --- URL: "https://mono-libs.netlify.app/lith/config" LLMS_URL: "https://mono-libs.netlify.app/lith/config.md" --- # Config: `path` and `url` `apps[].path` names the directory an app is read from; `apps[].url` names the repository `mono sync` clones it from. An entry needs at least one, `path` wins whenever its directory exists, and — the rule that makes a lith a lith — **`path` is honoured in every command**: dev server, `vite build`, `mono prepare`, `mono sync`, `mono env`, the Nuxt module and `monoNuxtLayers`. ```ts export interface MonoAppConfig { name: string /** Where `mono sync` clones from. Optional when `path` is set. */ url?: string /** Read this app from a directory instead of a clone. Authoritative everywhere. */ path?: string envToken?: string transport?: 'auto' | 'git' | 'token' type: 'vue' | 'nuxt' } ``` ## Three ways an entry can resolve | Declared | Directory exists | Result | |---|---|---| | `path` + `url` | yes | read in place; `mono sync` prints 🔗 and clones nothing | | `path` + `url` | **no** | one warning, then the `.mono/apps/` clone (`mono sync` fetches it from `url`) | | `path` only | yes | read in place | | `path` only | **no** | **error** naming the app and the resolved directory — nothing to fall back to | | `url` only | — | the clone, exactly as in Mono-Repo | | neither | — | config error, reported by name before anything else runs | The warning and the error both name the directory that was looked in: ``` [mono] esw-project: path '../esw-project' does not exist — using the synced clone instead. [mono] looked in C:\src\esw-ui\apps\esw-project ``` That fallback is what makes `path` safe to commit: the developer who has the sibling reads it, everyone else gets the clone. ## Writing the path - **Relative to the declaring file** (`apps/esw-host/mono.config.ts` → `'../esw-project'`), absolute paths kept as-is. - **A static string literal.** `mono.config.ts` is text-parsed before it can be executed (its `extends` chain imports other apps through aliases that do not exist yet), so `path: someVar` yields no alias rather than an error. - **Forward slashes.** The literal is evaluated as JavaScript, so `'..\esw-project'` silently becomes `'..esw-project'` and reads as "path does not exist". ## Own name, siblings of siblings Two things the resolver does that are easy to trip over: **An app named like the running app is skipped.** In a lith the host lists the remote and the remote lists the host back. When esw-project runs, the `esw-host` entry resolves to `../esw-host`; when esw-host runs, esw-project's `esw-host` entry is *itself* and `@esw-host` keeps meaning its own `src/`. **A sibling's own `path` entries are resolved too — one level, against that sibling's directory.** esw-host federates esw-project; esw-project's config names `esw-host` (skipped, that is us) and could name a third app `../esw-reports`. That third app gets an `@esw-reports` / `@esw-reports-root` alias in the host, so esw-project's `extends` chain can import `@esw-reports-root/mono.config` and load. One level only, never recursive, so the host ⇄ remote cycle cannot loop; a sibling's missing `path` is skipped silently — that sibling reports it when it runs. ::: warning What changes versus a clone In Mono-Repo, a cloned host arrives *without* its `.mono/`, so its remotes' configs were **stubbed** to `{ apps: [], extends: [] }` and contributed nothing. In a lith the sibling is right there, so a remote that `extends` its host now inherits the host's *other* siblings' merged config (menu, env, mock seeds) instead of a stub. That is the correct lith behaviour; it is also a difference you will notice if you compare the two. ::: ## Stale clones A `.mono/apps/` left over from before an app got a `path` is **shadowed, never deleted**. `resolveAppRoots` skips a clone whose name has a `path` root; `mono sync` keeps the name in its prune list (so the prune never touches it) and tells you it is there: ``` 🔗 esw-project: linked to ../esw-project — nothing to clone. ℹ️ a stale clone sits at .mono/apps/esw-project; it is shadowed by path and left alone — delete it if you want. ``` Nothing that reads a `path` ever writes to it or deletes it. `mono sync` prunes only inside `.mono/apps`, and `mono prepare` never touches a sibling's `tsconfig.json` (see [CLI & TypeScript](/lith/cli-typescript)). ## What was removed `path` used to be **dev-only** — a build always read the clone. That split is gone, and the options that encoded it are accepted but ignored: | Option | Was | Now | |---|---|---| | `monoRepo({ command })` | told the plugin whether to honour `path` | ignored; `path` is honoured in every command | | `monoRepo({ link })`, `monoAlias({ link })`, `monoEcosystem({ link })`, `monoMissingApps({ link })`, `monoNuxtLayers({ link })` | `false` = read the clone | `@deprecated`, ignored | | `MonoAppRoot.linked: boolean` | resolved from `path`? | `source: 'path' \| 'clone'` | A `link: false` left in a `vite.config.ts` type-checks and does nothing. A `resolveAppRoots` call that read `.linked` needs `.source === 'path'`. --- URL: "https://mono-libs.netlify.app/lith/dev-server" LLMS_URL: "https://mono-libs.netlify.app/lith/dev-server.md" --- # Dev Server & HMR Running the host reads every sibling live: an edit in `apps/esw-project` hot-updates the host in the browser, a page **added** to the sibling appears as a route, and a change to any `mono.config.ts` restarts the server. Vite does none of that for a directory outside its root on its own — `monoLith()` is the plugin that adds it, and `monoRepo().vite()` carries the same hooks. ## What Vite watches, and what it does not Vite watches its **root** (plus its own config dependencies and env files). A file outside the root enters the watcher only when it enters the module graph — so a sibling page that is already imported hot-updates fine, but: - a **new** `src/pages/*.vue`, `src/components/*.vue` or `src/composables/*.ts` in the sibling emits no `add` event, so unplugin-vue-router, unplugin-vue-components and unplugin-auto-import never learn of it; - `mono.config.ts` is loaded through c12/jiti at config time, outside Vite's config tracking, so the aliases, `__MONO_CONFIG_EXPOSE__`, the `extends` gate and every ecosystem dir go stale until you restart by hand; - anything outside the root is refused with a 403 unless `server.fs.allow` lists it. ## `monoLith()` ```ts // vite.config.ts (long-hand config: monoAlias + monoEcosystem by hand) import { monoLith } from '@mono-lit/utility/vite' export default defineConfig(async () => ({ plugins: [ VueRouter({ … }), vue(), // … monoLith({ dirname: fileURLToPath(new URL('.', import.meta.url)) }), ], })) ``` It resolves the same roots every other command uses and: | Hook | Does | |---|---| | `config` | adds every `path` root to `server.fs.allow` (restating the project root, since listing anything replaces Vite's default) | | `configureServer` | `server.watcher.add(/src)` for every `path` root, so new files reach the ecosystem plugins; watches this app's and every active app's `mono.config.ts` and calls `server.restart()` on change | | `resolveId` / `load` | provides [`virtual:mono-apps`](#virtual-mono-apps) | ```ts monoLith({ dirname, // project root; default process.cwd() restartOnConfigChange: true, // false = never restart watchSiblings: true, // false = do not add sibling src dirs to the watcher activeNames: ['esw-project'], // narrow virtual:mono-apps + the config watch list }) ``` `monoRepo().vite()` and `mono.plugin` already include these hooks — do not register `monoLith()` beside them. The `monoRepo` options `restartOnConfigChange` / `watchSiblings` are the same switches, and `mono.appRoots` exposes the resolved roots with their `source`. ## `virtual:mono-apps` A host merges its remotes' menus by loading each remote's `mono.config`. The glob that did this in Mono-Repo cannot see a sibling: ```ts // before — only ever saw clones const modules = import.meta.glob('../../.mono/apps/*/mono.config.ts') ``` `virtual:mono-apps` is one lazy import per federated app — sibling or clone — keyed by app name: ```ts // after import monoApps from 'virtual:mono-apps' // { 'esw-master': () => import('…/apps/esw-master/mono.config.ts'), 'esw-project': … } for (const [name, load] of Object.entries(monoApps)) { const { default: cfg } = await load() merge(cfg.menu) } ``` Types come from `@mono-lit/utility/virtual-mono-apps` — add to the app's `env.d.ts`: ```ts /// ``` The module lists the **other** apps, never the running one (its own config is `monoConfig()`), and only the `extends`-active ones under `monoRepo()`. Two notes: - The generated imports are absolute paths (the virtual module has no directory to be relative to). Vite serves them through `/@fs/` in dev and bundles them in a build. - Vite's dependency scanner does not crawl a virtual module, so a dependency reached *only* through one of these configs is discovered late ("new dependencies optimized, reloading"). In practice the same configs are also reached through the `extends` chain from `main.ts`, so this rarely shows. ## UnoCSS and other scanners Anything that scans files by glob needs the sibling directories. Get them from the resolver rather than hardcoding `.mono/apps`: ```ts // uno.config.ts import { resolveFederatedRoots } from '@mono-lit/utility/config/node' const remoteRoots = resolveFederatedRoots({ dirname }).map((r) => r.root.replace(/\\/g, '/')) export default defineConfig({ content: { filesystem: remoteRoots.flatMap((root) => [ `${root}/src/**/*.{js,ts,vue,html}`, `${root}/mono.config.ts`, // menu icon classes ]), }, }) ``` (Under `monoRepo()`, `mono.appRoots` is the same list.) ## Nuxt The Nuxt module follows the same rule — a `path` app is read in place in `nuxt dev` and `nuxt build` alike. A `type: 'nuxt'` sibling becomes a native Nuxt layer, and Nuxt watches every layer's `srcDir`, so Nuxt-to-Nuxt siblings get file-add HMR for free. A Vue sibling merged into a Nuxt host through `extendPages` is static, exactly as a clone was. --- URL: "https://mono-libs.netlify.app/lith/getting-started" LLMS_URL: "https://mono-libs.netlify.app/lith/getting-started.md" --- # Mono-Lith A **mono-lith** is the mono ecosystem with every app in ONE repository, each in its own folder, connected by `apps[].path` instead of a GitHub clone. The host reads its remotes in place — dev, build, `mono prepare` and `mono sync` all look at the same sibling directory — and editing a remote hot-updates the running host. It is the same federation as [Mono-Repo](/repo/getting-started): a host compiles its remotes' pages, components, composables and stores as its own, and a remote run standalone borrows the host's shell. What changes is *where the other app lives*: | | Mono-Repo (sync) | Mono-Lith (path) | |---|---|---| | One app = | one repository | one folder under `apps/` | | Remotes reach the host by | `mono sync` → `.mono/apps/` clone | `apps[].path: '../'` | | Editing a remote | push → `mono sync` on the host | the running host hot-updates | | A build reads | the clone | the sibling | | Lifting one app out | it already is its own repo | copy the folder; `url` takes over | ```mermaid graph LR subgraph esw-ui ["esw-ui (one repo, root runner)"] direction LR H["apps/esw-host
template: host"] M["apps/esw-master"] P["apps/esw-project"] H -- "path: ../esw-master" --> M H -- "path: ../esw-project" --> P M -- "path: ../esw-host" --> H P -- "path: ../esw-host" --> H end ``` Every arrow is a line in that app's own `mono.config.ts`. Each folder keeps carrying its own config, its own `package.json` and its own `pnpm-workspace.yaml` — so the folder can still be lifted out into a standalone checkout, where the sibling is gone and `mono sync` falls back to the `url`. ## Layout ``` esw-ui/ ├── package.json # the runner: dev / build / test via Vite+ (vp) ├── pnpm-workspace.yaml # apps/* + catalogs (lib versions), one install ├── .npmrc # the mono-libs registry for mono-*, npmjs for the rest ├── vite.config.ts # vite-plus: lint defaults + vitest projects └── apps/ ├── esw-host/ # the shell — template: 'host' │ ├── mono.config.ts # apps: [{ name: 'esw-project', path: '../esw-project', … }] │ ├── vite.config.ts # + monoLith() │ └── src/ ├── esw-master/ # apps: [{ name: 'esw-host', path: '../esw-host', … }] └── esw-project/ # apps: [{ name: 'esw-host', path: '../esw-host', … }] ``` Nothing under `apps//.mono/apps` is needed any more: `mono sync` reports each path app as **🔗 linked** and clones nothing. A stale clone left there from before is shadowed by the sibling and left alone. ## The config The host names its remotes by path and declares itself the shell: ```ts // apps/esw-host/mono.config.ts export default defineConfig({ name: 'esw-host', type: 'vue', template: 'host', // own layouts only, never a remote's apps: [ { name: 'esw-master', path: '../esw-master', url: 'https://github.com/org/esw-master/tree/mono', type: 'vue' }, { name: 'esw-project', path: '../esw-project', url: 'https://github.com/org/esw-project/tree/mono', type: 'vue' }, ], // env / fetching / menu / … exactly as before }) ``` Each remote names the host back, so it can run standalone with the host's shell: ```ts // apps/esw-project/mono.config.ts apps: [ { name: 'esw-host', path: '../esw-host', url: 'https://github.com/org/esw-host/tree/mono', type: 'vue' }, ] ``` `path` is relative to the file that declares it and must be a **static string literal with forward slashes** — the config is text-parsed before it can be executed. Everything about the rule is in [Config: path and url](/lith/config). ## When `url` still matters Keep the `url` beside the `path`. It costs nothing in the lith (`path` wins whenever the directory exists) and it is what makes a folder portable: - **Lifted out.** Copy `apps/esw-project` somewhere on its own: `../esw-host` is absent, `mono sync` clones the host from the `url` into `.mono/apps/esw-host`, and the app runs exactly as a Mono-Repo remote. - **CI that checks out one app.** Same story — the sibling is not there, the clone is. - **A `path` with no `url`** is fine too, but then a missing directory is an error rather than a fallback: there is nothing to sync from. ## Running it From the root (see [Root runner](/lith/root-runner)): ```bash pnpm install # once, at the root — one node_modules for every sibling pnpm dev # vp run --filter esw-host dev → the host, with both remotes live pnpm dev:project # esw-project standalone, wearing the host's shell pnpm build # the host bundle, remotes included, from the same siblings ``` Best practice is to develop and build **through the host**: that is the bundle that ships. Running a remote on its own is for working on it in isolation, and still reads the real host next door. --- URL: "https://mono-libs.netlify.app/lith/root-runner" LLMS_URL: "https://mono-libs.netlify.app/lith/root-runner.md" --- # Root runner (Vite+) The lith's root folder runs the apps; it is not an app itself. One `pnpm install` gives every sibling the same `node_modules`, and [Vite+](https://viteplus.dev) (`vp`) dispatches `dev`, `build` and `test` to the app you mean — the host by default. ## Why one install A host compiles its siblings' files. If `apps/esw-host` and `apps/esw-project` each had their own `node_modules`, a sibling page importing `vue` or `@mono-lit/helper` would resolve from *its* folder and the host would get a second copy of every runtime — two Vue instances, `mono-*` custom elements "already defined", Pinia stores that do not share state. In a single pnpm workspace every `apps/*/node_modules/vue` is a link into the same store entry, so Vite sees one module. ```yaml # pnpm-workspace.yaml packages: - apps/* catalogs: internal: "@mono-lit/devextreme": 0.0.1 "@mono-lit/utility": 0.0.1 "@mono-lit/helper": 0.0.1 build: { vite: 8.0.16, … } frontend: { vue: 3.5.24, pinia: 3.0.4, … } ``` ```ini # .npmrc — only the @mono-lit scope comes from the mono-libs registry; # every other package installs from npmjs as usual. @mono-lit:registry=https://mono-libs.netlify.app/npm/ //mono-libs.netlify.app/npm/:_authToken= ``` ```json // package.json { "packageManager": "pnpm@10.7.0", "pnpm": { "overrides": { "vue": "3.5.33", "pinia": "3.0.4", "devextreme": "25.1.6" } } } ``` Three things worth knowing: - **Each app keeps its own `pnpm-workspace.yaml`** (the same catalogs). pnpm ignores the nested file while installing from the root, and it is what lets a folder be lifted out and installed on its own. - **Catalogs need pnpm ≥ 9.5.** `packageManager` must not name an older pnpm — pnpm 10 would silently switch to it and the `catalog:` specs would fail. - **Only `apps/*` is in the workspace.** Never add a checkout of the libs themselves (or any package that ships its own `vite.config.ts`) — `vp run` loads every workspace package's Vite config to build its task graph. ## The libs `@mono-lit/utility`, `@mono-lit/helper` and `@mono-lit/devextreme` are **versioned releases** on the mono-libs registry (`.npmrc` above; the versions live in `catalogs.internal`). A lith app therefore installs exactly like a Mono-Repo app — no local `libs` checkout is involved. Shipping a lib change is a release: in the `libs` repo bump the package's `package.json` and append the version to `version.json`, run `REGISTRY_PUBLISH_TOKEN=… pnpm registry:publish` (versions are immutable; devextreme → utility → helper), then raise the version in the catalog here and `pnpm install`. `apps[].path` works with every `@mono-lit/utility` release. ::: tip Iterating on a lib without publishing Point the root overrides at a local checkout for the duration — `"@mono-lit/utility": "link:../../libs/packages/utility"` — and remove the override before committing. A rebuild in `libs` is then live in every sibling. ::: ## Scripts ```json { "scripts": { "dev": "vp run --filter esw-host dev", "dev:master": "vp run --filter esw-master dev", "dev:project": "vp run --filter esw-project dev", "build": "vp run --filter esw-host build", "build:dev": "vp run --filter esw-host build:dev", "build:all": "vp run -r build", "test": "vp test", "mono:prepare": "vp run -r mono:prepare" } } ``` `vp run --filter ``` ::: tip Why `:data-source.prop`? A DataSource is an object. On a custom element, Vue would stringify a plain `:data-source` binding into an attribute — so you must use the **`.prop`** modifier to pass it as a real DOM property. ::: ## Need one record? `load({ take: 1 })`, never `byKey()` To pull a single row from a DataSource, query it through `load` — add a `filter` if you're matching on a field: ```ts const [first] = await ds.value.load({ take: 1 }) // matching a specific row: const [match] = await ds.value.load({ filter: ['Id', '=', id], take: 1 }) ``` ::: danger Don't use `ds.value.store().byKey(id)` Once a DataSource is bound to a component, `byKey` reads from / **caches against the data already loaded into that DataSource** — so it can hand you a **stale, cached** row (or `undefined` for one that was never paged in) instead of a fresh result. Always use `load({ take: 1 })` (with a `filter` when needed); it goes through the source's normal query path and returns live data. ::: ## Components that accept a DataSource The same `dataSource` works across these components: ### `mono-select` A single-value picker. Bind `:data-source.prop`, map fields with `key-value` / `display-value`, and page with `load-more="scroll"` (or `"button"`). See [Select](/ui/select). ```vue ``` ### `mono-tag-input` Multi-value version — same props, plus `:immediate.prop="true"` to load on mount. See [Tag input](/ui/tag-input). ```vue ``` ### `mono-table` A native table. Wrap the DataSource in a `controlMonoTable` controller, then bind the controls with `:control-table.prop`. See [Table](/ui/table). > No remote data? Pass a **plain array** straight to `controlMonoTable` — > `controlMonoTable(rows, { pageSize: 10, searchValue: ['UserName', 'LastName'] })` — and it > pages, searches and sorts in memory. Swap rows later with `table.setData(next)`. ```vue ``` --- URL: "https://mono-libs.netlify.app/odata/expression" LLMS_URL: "https://mono-libs.netlify.app/odata/expression.md" --- # OData Expression OData is a REST protocol with a **standard query language built into the URL** — you shape the response with `$`-prefixed options like `$select`, `$filter` and `$expand` instead of asking the backend for a new endpoint. This page explains those options and shows how to send each one through `monoFetchOdata`, live against a public OData v4 service. ## What is OData A plain REST endpoint returns whatever the backend decided to return. An OData endpoint returns whatever **you** ask for, because the query is part of the URL: ``` GET https://services.odata.org/TripPinRESTierService/People ?$select=UserName,FirstName &$filter=contains(FirstName,'A') &$orderby=FirstName &$top=5 ``` Three things come with that: - **One endpoint, many shapes.** Fewer fields, filtered rows, sorted, paged — no backend change. - **A published schema.** Every service exposes `$metadata` describing its entities. That is what [OData Types](./types) generates TypeScript from. - **The work happens on the server.** Filtering and aggregation run in the database, not in the browser. The `$`-prefixed parts are called **system query options**. They are the whole subject of this page. ## System Query Options `monoFetchOdata` gives you two ways to send them: | Channel | What you write | What happens | | --- | --- | --- | | **`options`** | The DevExtreme shape — `select`, `expand`, `filter`, `sort`, `pageSize`, `pageIndex`, `requireTotalCount` | DevExtreme translates it into the `$` params. **You never write `$` keys here.** | | **`params`** | A raw query-string map — `{ $apply: '…' }` | Sent through verbatim. The only way to reach options DevExtreme has no equivalent for. | The full list: | Option | What it does | Example | | --- | --- | --- | | `$select` | Return only these fields | `$select=UserName,FirstName` | | `$expand` | Inline a related entity | `$expand=Trips` | | `$filter` | Keep only matching rows | `$filter=Age gt 30` | | `$orderby` | Sort the result | `$orderby=LastName desc` | | `$top` | Take at most N rows | `$top=10` | | `$skip` | Skip the first N rows | `$skip=20` | | `$count` | Include the total row count | `$count=true` | | `$search` | Free-text search | `$search=Boise` | | `$apply` | Group and aggregate server-side | `$apply=groupby((Gender),aggregate($count as Total))` | | `$compute` | Add a calculated field to the result | `$compute=Budget mul 2 as Doubled` | | `$format` | Response format | `$format=json` | | `$index` | Insert position in a collection | `$index=0` | | `$schemaversion` | Pin the schema version | `$schemaversion=1.0` | ::: tip Nested options need `params` `options.expand` only takes plain navigation names. To put inner options inside an expand — `$expand=Trips($select=Name;$top=1)` — write it as a raw param instead: ```ts params: { $expand: 'Trips($select=Name,Budget;$top=1)' } ``` ::: ::: tip Paging is `pageSize` / `pageIndex`, not `take` / `skip` `monoFetchOdata` builds a DevExtreme DataSource, and a DataSource pages itself: `pageSize` becomes `$top` and `pageIndex` becomes `$skip` (the offset is `pageIndex * pageSize`). A `take` or `skip` passed in `options` is ignored, and you silently get the DataSource default `$top=20` instead. ::: ::: warning `$apply` needs `paginate: false` When you send `$apply`, also set `options.paginate = false`. Otherwise DevExtreme attaches its default `$top=20` and silently truncates the aggregation buckets. ::: For the operators and functions you can use inside `$filter` (`eq`, `gt`, `contains`, `startswith`, `any`/`all`, …), see the reference in [Mock API](../repo/mock-api). ## Try it Each tab is a real request against the public [TripPin](https://services.odata.org/TripPinRESTierService) OData v4 service. Switch tabs to change the example, then press **Run**. The snippet in each tab is not a mock-up — it is the exact `monoFetchOdata` call the button executes, rendered from the same argument object that gets passed in. After a run the panel also shows the **actual request URL** the browser sent, read back from the browser's own resource timings, so you can see precisely which `$` params came out the other end. ## See also - [Data Fetching](../repo/data-fetching) — configuring `fetching.api`, `configBaseUrl`, and auth tokens. - [OData Types](./types) — generating TypeScript types from `$metadata`. - [DataSource](./datasource) — `monoCreateFetcher` and binding a live DataSource to a component. - [Mock API](../repo/mock-api) — the supported `$filter` operators and the `$apply` pipeline. --- URL: "https://mono-libs.netlify.app/odata/types" LLMS_URL: "https://mono-libs.netlify.app/odata/types.md" --- # OData Types Every OData service publishes a `$metadata` document describing all of its entities and their fields. Instead of hand-writing TypeScript interfaces for those entities (tedious, and they drift out of sync with the backend), you **generate** them from `$metadata` with [`odata2ts`](https://odata2ts.github.io/). There's one catch: odata2ts emits **query-object classes** (the `Q*` objects used to build type-safe OData queries), not plain field shapes. So the workflow has a small mapping step — turn the raw `Q*` class into a normal type with `MonoOdataMapTypes` from `@mono-lit/utility/runtime`. After that the type is safe to use anywhere in the app. The four steps: 1. [Configure the service](#step-1-configure-odata2ts-config-ts) in `odata2ts.config.ts`. 2. [Generate](#step-2-generate-the-classes) the classes into `src/odata/`. 3. [Map](#step-3-map-the-raw-q-classes-to-normal-types) the raw `Q*` classes to plain types. 4. [Use](#step-4-use-the-mapped-types-across-the-app) the mapped types across the app. ## Step 1 — Configure `odata2ts.config.ts` `odata2ts.config.ts` (at the app root) lists every OData source under `services`. **Each key is unique and becomes the folder name** generated under `src/odata/`. ```ts // odata2ts.config.ts import type { ConfigFileOptions } from '@odata2ts/odata2ts' import dotenv from 'dotenv' dotenv.config() const sourceUrl = `${String(process.env.MONO_VUE_ODATA_BASE_URL)}` const config: ConfigFileOptions = { services: { DTO: { sourceUrl, // the OData root (from an env var) source: 'src/odata/DTO/metadata.xml', // local metadata snapshot output: 'src/odata/DTO', // where generated files go }, }, } export default config ``` - **`DTO`** — the unique service key → output folder `src/odata/DTO`. - **`sourceUrl`** — the OData base URL. Keep it in an env var (`MONO_…`, see [Environment](../repo/env) / Rule 6) — never hardcode it. - **`source`** — the local `metadata.xml` snapshot odata2ts reads/writes. - **`output`** — the target folder for the generated code. #### Many OData sources in one config Add another key for a second service — it gets its **own folder**: ```ts services: { DTO: { sourceUrl: `${String(process.env.MONO_VUE_ODATA_BASE_URL)}`, source: 'src/odata/DTO/metadata.xml', output: 'src/odata/DTO', }, Reporting: { // → src/odata/Reporting sourceUrl: `${String(process.env.MONO_VUE_REPORTING_ODATA_URL)}`, source: 'src/odata/Reporting/metadata.xml', output: 'src/odata/Reporting', }, }, ``` ## Step 2 — Generate the classes Run the generation script from `package.json`: ```bash pnpm odata:gen # dotenv -e .env.dev odata2ts ``` It loads `.env.dev` (so `MONO_VUE_ODATA_BASE_URL` resolves), reads the metadata, and writes the typed output into each service's `output` folder. A `src/odata/DTO/` folder ends up with: | Generated file | What it is | | --- | --- | | `QDefault` | The **query-object classes** — e.g. `QDTO_Brand`, `QDTO_MasterUser`. These are what you map in Step 3. | | `DefaultModel` | The DTO model interfaces + enums. | | `DefaultService` | OData service/entity-set classes. | | `metadata.xml` | The metadata snapshot odata2ts read from. | > There's also `pnpm odata:github` for pulling metadata from a GitHub source instead of a > live URL. ::: danger Generated — never hand-edit Everything under `src/odata//` is regenerated on every run. Don't edit it by hand — your changes vanish and you hide the real source (the metadata). This is **Rule 4** in [Template Rules](../ai/template). To change the types, fix the backend / regenerate. ::: ## Step 3 — Map the raw `Q*` classes to normal types The generated `Q*` objects describe fields as query paths (`QStringPath`, `QNumberPath`, …), not as a plain shape you can put in a `ref`. **`MonoOdataMapTypes`** (from `@mono-lit/utility/runtime`) unwraps them into a normal type. Do this once per entity in `src/types/odata.d.ts`: ```ts // src/types/odata.d.ts import type { QDTO_Brand, QDTO_MasterUser, } from '@mono-vue/odata/DTO/QDefault' import type { MonoOdataMapTypes } from '@mono-lit/utility/runtime' export type DTO_BrandTypes = MonoOdataMapTypes export type DTO_MasterUserTypes = MonoOdataMapTypes // hand-written shapes (e.g. a POST body) still live alongside as plain types export type BrandPostTypes = { Nama: string NamaBudget: string } ``` `MonoOdataMapTypes` reads the `Q*` class and unwraps each path to its real value type: | Generated path | Becomes | | --- | --- | | `QStringPath` | `string` | | `QNumberPath` | `number` | | `QBooleanPath` | `boolean` | | `QDateTimeOffsetPath` | `string` | | `QEntityPath` | the nested mapped object | | `QEntityCollectionPath` | the nested mapped object **as an array** | So `DTO_BrandTypes` resolves to `{ Id: number; Nama: string; NamaBudget: string; Aktif: boolean; DibuatTanggal: string }`. It also accepts an optional second generic to **override** specific fields with another mapped type when you need to. ::: tip Import through your app's own alias The `Q*` objects are imported via the **role-based resolve alias** — `@mono-vue/...` in a Remote, `@mono-host/...` in the Host. Each alias points at that app's own `./src` (see Rule 1 / Rule 2 in [Template Rules](../ai/template)), so the generated types resolve correctly and stay safe to use across the ecosystem. ::: ## Step 4 — Use the mapped types across the app The mapped types are now ordinary TypeScript — use them in store state, as fetch generics, and to constrain table columns. ```ts // src/stores/use-master-user.ts import type { DTO_MasterUserTypes } from '@mono-vue/types' import { monoFetchOdata } from '@mono-lit/utility/fetching' export const useMasterUser = defineStore('master-user', () => { const detail = ref(null) async function fetchDetail(id: number) { const { data, error } = await monoFetchOdata({ configBaseUrl: 'myOdata', url: `/DTO_MasterUser(${id})`, type: 'data', options: { select: ['Id', 'Username', 'NamaLengkap'], expand: ['Role'] }, }) if (!error) detail.value = data } return { detail, fetchDetail } }) ``` Because the type is a plain shape, `keyof` works too — handy for typing table column definitions so a typo'd field name fails at compile time: ```ts // src/datas/tables/user.ts import type { DTO_MasterUserTypes } from '@mono-vue/types' export interface UserCol { field: keyof DTO_MasterUserTypes | string caption: string sortable?: boolean } const colUser: UserCol[] = [ { field: 'Username', caption: 'Username', sortable: true }, { field: 'NamaLengkap', caption: 'Nama Lengkap', sortable: true }, { field: 'Nik', caption: 'NIK' }, ] ``` Fetching itself still goes through `@mono-lit/utility/fetching` — see [Data Fetching](../repo/data-fetching) and [DataSource](./datasource). ::: tip Recap Generate (`odata2ts`) → map (`MonoOdataMapTypes`) → use. The generated `src/odata//` folder is read-only (Rule 4); your only hand-written file in this flow is `src/types/odata.d.ts`. See [Template Rules → Rule 11](../ai/template) for the short version. ::: --- URL: "https://mono-libs.netlify.app/repo/config" LLMS_URL: "https://mono-libs.netlify.app/repo/config.md" --- # Config The mono-repo also comes with a config file that handles cookies, JWT state, and deployment. > Apps living side by side in one repository? `apps[].path` reads a sibling folder in place — see [Mono-Lith → Config](/lith/config). The config lives in a single file: ``` mono-vue-remote/ ├── mono.config.ts └── ...etc/ ``` ## Setup Start by creating a file named `mono.config.ts` with a default config like this: ```ts import { defineConfig } from "@mono-lit/utility/runtime"; export default defineConfig({ name: 'mono-remote', }); ``` Then register it when your app starts. How you do that depends on the app kind — a **Vue** app calls `createMono` in `src/main.ts`, a **Nuxt** app uses the mono modules plus a plugin. See [Setup](./setup) for the per-kind wiring. The rest of this page covers what you can put **inside** `mono.config.ts`. ## App type — Vue or Nuxt `type` tells the ecosystem whether an app is **Vue** or **Nuxt**, which sets where its source lives (`src/` or `app/`) and how the two apps reach each other's folders. The [Setup](./setup) page explains how that drives the build; here's how you declare it in `mono.config.ts`. It appears in two places: - **`type` at the config root** declares **this** app's kind. - **`apps[].type`** declares **each synced** app's kind, so this app resolves the *other* app's folders to `.mono/apps//src` or `.mono/apps//app` correctly. ::: warning Declare `type` above `apps` The alias builder (`monoAlias`, used internally by `monoRepo()` and the `@mono-lit/utility/nuxt` module) parses the config **text** statically, before the file is executed — so `type` must appear **above** the `apps` array. Otherwise the parser hasn't seen it yet and falls back to `src/`. ::: ::: warning The examples below show the hybrid pairing A Nuxt Host joined with a Vue Remote still works — mono's compat layer holds it together — but it is **possible-but-risky** and outside the standard. The **standard is a same-framework pair**: Vue Host ↔ Vue Remote, Nuxt Host ↔ Nuxt Remote. The hybrid appears here only because it is the clearest way to show both `type` values in one file. See [Setup](./setup). ::: A Nuxt host with a Vue remote synced into it: ```ts import { defineConfig } from '@mono-lit/utility/config' export default defineConfig({ name: 'mono-host', // This host is a Nuxt app -> source under `app/`. Declared above `apps`. type: 'nuxt', apps: [ { name: 'mono-vue', url: 'https://github.com/mono-lit/templates/tree/main/vue-remote', envToken: 'MONO_NUXT_HOST_GITHUB_TOKEN', // mono-vue is a Vue app -> its synced source lives under `src/`. type: 'vue', }, ], }); ``` And the mirror — a Vue remote whose host is Nuxt. Here `apps[0].type` is `nuxt`, so `@mono-host` resolves into the synced host's `app/` folder: ```ts import { defineConfig } from '@mono-lit/utility/config' export default defineConfig({ name: 'mono-vue', type: 'vue', apps: [ { name: 'mono-host', url: 'https://github.com/mono-lit/templates/tree/main/nuxt-host', envToken: 'MONO_VUE_GITHUB_TOKEN', // mono-host is a Nuxt app -> `@mono-host` resolves to `app/…`, not `src/…`. type: 'nuxt', }, ], }); ``` See [Sync](./sync) for how `apps` is pulled into `.mono/apps/`. ## App role — Host or Remote `template` says which side of the federation this app is: ```ts export default defineConfig({ name: 'mono-host', type: 'vue', template: 'host', // this app OWNS the shared shell // … }) ``` It is **orthogonal to `type`**. `type` says where the source lives (`src/` or `app/`); `template` says whether this app owns the shared shell or consumes it. | `template` | Layouts `mono.layouts.options()` returns | | --- | --- | | `'host'` | This app's own `layouts/` only. A federated app's `default.vue` must not compete with the shell's. | | `'remote'` | This app's own (if any) **plus** every federated app's — how a Remote gets the Host's shell. | | *omitted* | Same as `'remote'`. This is the pre-`template` behaviour, so adding the field breaks nothing. | That is the only thing it changes today. Everything else that used to differ between a Host and a Remote is derived — the Nuxt-compat transforms from `apps[].type`, the source dir from `type`, and the federated root-`index.vue` exclusion from whether this app ships its own `pages/index.vue`. Layouts are the one case nothing on disk can settle: an app with no `layouts/` folder looks identical in either role. ::: warning `template` is never inherited through `extends` A Remote normally extends its Host. If `template` were inherited, a Remote that omits it would silently become a `'host'` — dropping the very layouts it extends the Host to get, with no error to notice. So, like `name` and `type`, it is read from **this file only** and is excluded from the `merges` allowlist described below. ::: To override for one call, use the plugin’s own option — it replaces the whole list: ```ts Layouts(mono.layouts.options({ layoutsDirs: ['src/layouts', ...mono.ecosystem('layouts')] })) ``` ## Skills repository `skill` (optional) names the git repository where `mono skills` reads this app's knowledge and saves AI session history — see [Skills (for AI)](../ai/skills). Its **presence is the switch**: leave it out and the whole workflow is a no-op. ```ts export default defineConfig({ name: 'gallery-apps', type: 'vue', skill: { url: 'https://github.com/my-org/app-knowledge.git', // any git host; or a GitHub // deep URL to write into a folder on a branch: // 'https://github.com/my-org/monorepo/tree/mono/knowledge' envToken: 'APP_KNOWLEDGE_TOKEN', // optional: env var NAME, same idea as apps[].envToken }, apps: [/* … */], }) ``` | Key | Meaning | | --- | --- | | `url` | Plain clone URL (`https://…/repo.git`, `git@host:org/repo.git`) → default branch, repo root. GitHub `…/tree//` → branch ``, everything under ``. | | `envToken` | The **name** of an env var holding a PAT. Only read when this machine's own git credentials can't reach the repo (not invited / no credential). HTTPS URLs only. | Both must be **static string literals** — the CLI text-parses this file, like `apps[]`. ::: warning `skill` is never inherited through `extends` Like `template`, it describes **this** app: which repository its session history belongs to. A Remote extending a Host that declares `skill` does not start filing sessions into the Host's repo — each app declares its own (the same repo, if that's what you want). It is excluded from the `merges` allowlist below. ::: ## Extends `apps` says which remotes to **clone**; `extends` says which of them are **switched on**. An app kept in `apps` but absent from `extends` is still synced, yet it contributes no config and no directories — that is the on/off switch. Each entry is a thunk. The thunk (rather than the config object directly) is what lets two configs extend each other without hitting the ESM circular-import trap: ```ts import monoHostConfig from '@mono-host-root/mono.config' export default defineConfig({ name: 'gallery-apps', type: 'vue', extends: [ (): MonoConfig => monoHostConfig, ], // … }); ``` Your own config always wins. Layers only fill in what you did not declare, and name-keyed arrays (`apps`, `menu`, `cookie`) merge per key with your entry leading the list. ### Taking only part of a layer A bare thunk merges everything the layer has — its `menu`, `env`, `cookie`, `fetching`, `jwt`, `mockIndexedDB`, **and** every directory it owns. To take less, swap the thunk for an options object: ```ts extends: [ (): MonoConfig => flowAppConfig, // everything { config: (): MonoConfig => galleryAppConfig, merges: ['menu', 'mockIndexedDB'], // only these config keys ecosystems: ['pages', 'composables', 'stores'], // only these directories }, ], ``` | | Omitted | Listed | `[]` | | --- | --- | --- | --- | | `merges` | every config key | only those keys | no config at all | | `ecosystems` | every directory | only those directories | no directories at all | Omitting a key means "no restriction", so `{ config }` on its own behaves exactly like the bare thunk — selectivity is opt-in and nothing existing changes. ::: tip `ecosystems` outranks your build config The allowlist is applied inside `mono.ecosystem()` and inside the Nuxt module's own discovery, not at the call site. So a layer that did not list `components` contributes nothing to `...mono.ecosystem('components')`, however that call is written. Your **own** `'./src/components'` is untouched — only what the layer contributes is filtered. ::: Matching is segment-wise, so `'composables'` also admits `'composables/shared'`, while `'composables/shared'` admits only itself. The common use is a remote declining part of its host while developing: ```ts // in the remote — use the host's pages, but not its layouts or components extends: [ { config: (): MonoConfig => monoHostConfig, ecosystems: ['pages'] }, ], ``` Because `merges` and `ecosystems` are independent, that remote still receives the host's `fetching`, `cookie` and `jwt` in full. Drop `ecosystems` again for production and the remote consumes everything the host provides. Two things `merges` deliberately cannot change: `name` and `type` identify a config rather than describe shared state, so they are never taken from a layer. And listing `apps` is not required to keep a remote registered — the Vite and Nuxt integrations both restore `apps` from your own config after merging. ## Cookie Handling a cookie is simple. Say you have a cookie called `JWT_Token` that's already set, and you want to use it across your app — here's a small example. ```ts import { defineConfig, JWTCompleteTokenTypes } from "@mono-lit/utility/runtime"; export default defineConfig({ name: 'mono-remote', cookie: [ { name: 'JWT_Token', }, ], }); ``` Then use it like this — it returns the exact value of your token: ```ts import { monoState } from '@mono-lit/utility/state'; const token = monoState().cookie.JWT_Token console.log(token) ``` An entry may also declare `split: true`, for a token too large for one cookie (it's stored across numbered chunks). Declare it here once: `fetching.auth` refers to these cookies **by name** and inherits the flag, so nothing else has to restate it. See [Data Fetching](./data-fetching#adding-a-jwt-token) for how a cookie declared here becomes the token on every request. ## JWT What if you need to decode the `JWT_Token` cookie to read the JWT payload inside? Set it up like this: ```ts //@unocss-include import { defineConfig, JWTCompleteTokenTypes } from "@mono-lit/utility/runtime"; export default defineConfig({ name: 'mono-remote', // your app name jwt: { token: { name: 'JWT_Token', }, }, }); ``` Then use it like this — the token returns the decoded value: ```ts import { monoState } from '@mono-lit/utility/state'; const { jwt } = monoState() console.log(jwt.token) ``` ### More than two tokens `token` and `refreshToken` are just the two keys mono knows by name. The block takes **any** key, so an app carrying a third JWT — a vendor token, an impersonation token, a second identity provider — has somewhere to put it. Each key decodes its cookie and hydrates into `monoState().jwt.`: ```ts jwt: { token: { name: 'JWT_Token', split: true }, refreshToken: { name: 'JWT_RefreshToken' }, // any key you like: vendorToken: { name: 'VENDOR_jwt', split: true }, }, ``` ```ts const { jwt } = monoState() jwt.token.USER_NAME // typed — `token` and `refreshToken` have known claims jwt.vendorToken // Record ``` A custom key reads as an untyped claims bag. To give it real types, pass them through the `monoState` generic: ```ts interface VendorClaims { vendor: string; scope: 'read' | 'write' } const { jwt } = monoState<{ jwt: { vendorToken: VendorClaims } }>() jwt.vendorToken.scope // 'read' | 'write' ``` ::: warning A mis-cased key is not a compile error Accepting any key means TypeScript can't flag `refreshtoken` (lowercase `t`) as a typo — it's a perfectly valid custom key. It would hydrate under *that* name and leave `monoState().jwt.refreshToken` empty, so every guard reading it sees a logged-out user. mono warns in the console when a key looks like a mis-cased known one, since the type system no longer can. ::: ## Deployment Deployment is fully handled by the Host, so the Host needs to know which Remote pages to deploy. For example, a Remote has a page called `budget.vue`: ``` mono-vue-remote/ └── src/ └── pages/ └── budget.vue ``` To have the Host deploy it, define it in the config. You can use any icon from [Icones](https://icones.js.org). ```ts import { defineConfig, JWTCompleteTokenTypes } from "@mono-lit/utility/runtime"; export default defineConfig({ name: 'mono-remote', menu: [ { title: 'Budget', url: '/budget', icon: 'i-mdi-wallet-bifold', } ] }); ``` --- URL: "https://mono-libs.netlify.app/repo/data-fetching" LLMS_URL: "https://mono-libs.netlify.app/repo/data-fetching.md" --- # Data Fetching To set up fetching, you need three things: a base URL, a token, and the fetch function. Mono ships with all of them. Inside your `mono.config.ts`, define a `fetching` object. `api` is a **named map** — each entry has a required `url`, a `type` (`'restful'` or `'odata'`), and, for odata, its own `oDataService`. The shared DevExtreme source constructors (`dataSource` / `oDataStore` / `customStore`) are the same for every odata API, so they live once on `fetching.source`: ```ts import { defineConfig } from '@mono-lit/utility/config' import DataSource from 'devextreme/data/data_source' import ODataStore from 'devextreme/data/odata/store' import CustomStore from 'devextreme/data/custom_store' import { DefaultService } from './odata/DefaultService' export default defineConfig({ name: 'mono-vue', fetching: { api: { Posts: { type: 'restful', url: 'https://jsonplaceholder.typicode.com', }, MyApi: { type: 'odata', url: 'https://services.odata.org/V4/Northwind/Northwind.svc', // unique per odata API: oDataService: DefaultService, }, }, // shared by every odata API: source: { dataSource: DataSource, oDataStore: ODataStore, customStore: CustomStore, }, } }); ``` You then pick which named API a call uses with **`configBaseUrl: ""`**. It resolves that entry's `url` (and, for odata, the shared `source` ctors plus that entry's `oDataService`), overriding the call's own `baseUrl`. ## Adding a JWT Token Both fetch functions — `monoFetch` and `monoFetchOdata`, covered in [Fetching](#fetching) below — read this same config, so you define the token once and every call carries it. Set up your `mono.config.ts` like this: ```ts import { defineConfig } from '@mono-lit/utility/config' export default defineConfig({ name: 'mono-host', fetching: { api: { Posts: { type: 'restful', url: 'https://jsonplaceholder.typicode.com', }, MyApi: { type: 'odata', url: 'https://services.odata.org/V4/Northwind/Northwind.svc', }, }, auth: { use: { // sent on every API request apiRequest: 'Your_Refresh_Token', // sent as the Bearer ON the refresh request itself refreshTokenRequest: 'Your_Token', }, }, }, cookie: [ { name: 'Your_Token', split: true, }, { name: 'Your_Refresh_Token', } ], }); ``` `use` names cookies you already declared in `cookie[]` — so each one's `split` flag is inherited from there rather than restated. The two keys say **what each cookie is for**: | Key | The cookie that… | | --- | --- | | `apiRequest` | goes out as the Bearer on every `monoFetch` / `monoFetchOdata` call | | `refreshTokenRequest` | authenticates the **refresh call itself** — typically the JWT you got at login | ::: tip They're meant to look backwards In the example above, `apiRequest` names the *refresh* cookie and `refreshTokenRequest` names the *login* one. That is not a typo. Which cookie you send on an API call and which one buys you a new token are separate questions, and in this backend they happen to be the opposite of what the names suggest. Read each key as "the cookie used **for** this", not "the cookie **called** this". ::: ::: tip Migrating The older form — `auth: { token, tokenRefresh, use: 'tokenRefresh' }` — still works, but it can't drive the automatic refresh below. `use` has to name the cookies for that. ::: ### Reading the cookie names in your app Login, logout and route guards still need the cookie names by hand. Resolve them **once**, from the config, and export them alongside it: ```ts // src/datas/config.ts (Vue) · app/datas/config.ts (Nuxt) const monoConfig = __MONO_CONFIG_EXPOSE__ const use = monoConfig.fetching?.auth?.use const authCookie = { /** the JWT written at login; also the Bearer sent ON the refresh request */ jwt: typeof use === 'object' ? String(use.refreshTokenRequest) : '', /** the token sent on every API request — what a refresh re-issues */ jwtRefresh: typeof use === 'object' ? String(use.apiRequest) : '', } export default { ...monoConfig, authCookie, } ``` Then read `appConfig.authCookie.jwt` wherever you need it. `use` also accepts the legacy string form, so it has to be narrowed before you can read `.apiRequest` off it — doing that here, once, keeps the `typeof` check out of every call site. ::: warning Don't reach for `auth.token` / `auth.tokenRefresh` Those keys are deprecated, and reading them once you've moved to `use` gives you `undefined` — which `String()` happily turns into a cookie **named `"undefined"`**. No error, no warning: every request just goes out unauthenticated and every guard sees a logged-out user. ::: ## Fetching Call `monoFetch` as your fetch function. Point it at a named entry with `configBaseUrl`, or pass a `baseUrl` directly. `monoFetchOdata` works the same way, but targets an `odata` entry — `configBaseUrl` resolves both the base URL **and** the source constructors from that entry. The difference is the **options** field, which shapes the OData result. ::: code-group ```vue [Normal Fetching] ``` ```vue [OData Fetching] ``` ::: ## Automatic Token Refresh Add `requestRefreshTokenRequest` and mono refreshes the token for you — proactively before a request, and again on a `401` (the request is then retried once). Without it, nothing refreshes: the token is simply read from its cookie and sent. ```ts auth: { use: { apiRequest: 'Your_Refresh_Token', refreshTokenRequest: 'Your_Token', }, requestRefreshTokenRequest: { // the cookie the new token is written back to name: 'Your_Refresh_Token', // where to find each value in the RESPONSE body path: { milis: 'Expired', value: 'RefreshToken', }, splitCookie: false, fetchParams: { url: '/Auth/RefreshToken', options: { method: 'POST', baseUrl: import.meta.env.VITE_API_BASE_URL, }, }, }, }, ``` The refresh request authenticates itself with the `use.refreshTokenRequest` cookie — you don't attach it by hand. `name`, `splitCookie` and `baseUrl` are all optional: | Omitted | Falls back to | | --- | --- | | `name` | the `apiRequest` cookie | | `splitCookie` | that cookie's `split` flag, as declared in `cookie[]` | | `baseUrl` | a **`restful`** entry in `fetching.api` — the one the triggering call used if it is REST, otherwise the first `restful` entry you declared (and finally any `restBaseUrl` set via `monoConfigureFetching`) | ::: warning Set `baseUrl` explicitly A refresh endpoint is a REST route, but the call that *triggers* a refresh is often an OData one — and an OData entry's `url` is the `/odata` root. That's why the fallback hunts for a `restful` entry rather than reusing the triggering call's base: inheriting it would POST `/odata/Auth/RefreshToken` and 404 on every refresh, from a config that reads perfectly fine. The fallback covers the common case; naming the base yourself removes the guesswork. ::: ::: warning `path.milis` (or `path.days`) is required That's the cookie **lifetime**, read out of the response. With neither, the refreshed token is never written to the cookie — the refresh appears to succeed and changes nothing, and every subsequent request still carries the old token. mono warns at runtime if you omit it. ::: ### Which token actually gets sent In precedence order: a `token` passed on the call itself, then one set via `monoConfigureFetching({ token })`, then the `use.apiRequest` cookie. The same rule applies to `config` and `tokenOptions` — pass your own on a call and it wins over the config. mono reads that cookie **live** on every request rather than trusting the value hydrated at boot. It has to: a refresh writes the new token straight to `document.cookie`, so reading the hydrated copy would keep sending the pre-refresh token forever. The refreshed token is picked up by the very next call, and mono state is patched to match. ### Where the request goes when refresh fails `unauthCall` is the usual answer: it fires when a token is expired and the refresh couldn't save it. It needs the router, so it's registered at runtime rather than in `mono.config.ts`. ::: code-group ```ts [Vue — src/main.ts] import { monoConfigureFetching } from '@mono-lit/utility/fetching' import router from './router' monoConfigureFetching({ unauthCall: () => router.push('/'), }) app.use(createMono(monoConfig)) app.use(router) ``` ```ts [Nuxt — app/plugins/mono.ts] import { monoConfigureFetching } from '@mono-lit/utility/fetching' export default defineNuxtPlugin((nuxtApp) => { if (import.meta.client) { const router = useRouter() monoConfigureFetching({ unauthCall: () => router.push('/'), }) } nuxtApp.vueApp.use(createMono(monoConfig)) }) ``` ::: The blunt alternative — reload the page and let the app re-bootstrap: ```ts auth: { expiredBehaviour: 'refresh' } ``` Registering `unauthCall` **short-circuits** `expiredBehaviour` — set both and only `unauthCall` runs. ::: info Mock API Requests served by [`mockIndexedDB`](/repo/mock-api) never carry a token and never trigger a refresh. The mock has no auth surface, so you can leave `auth` fully configured while developing against it. ::: --- URL: "https://mono-libs.netlify.app/repo/env" LLMS_URL: "https://mono-libs.netlify.app/repo/env.md" --- # Environment Each app keeps its own environment variables. **mono-env** is a small wrapper (shipped with **@mono-lit/utility**) that loads a *root* env file first, then layers each app's env file from `.mono/apps/` on top, and finally runs your real command (`vite`, `vue-tsc`, …) with the merged environment. You don't call it directly — it's already wired into every script in the [templates](../ai/template), so day to day you just run `pnpm dev` / `pnpm build`. ``` mono env -e .env.dev -- vite ``` That single line means: *load `.env.dev` (root, then every app), then run `vite`*. ## Where env values live There are two homes for "environment" values, and in a federation picking the right one matters — because the **host consumes its remotes' config**, so what you *expose* versus *hide* is a real decision: - **`.env` files** — normally *not* pushed. For secrets and per-machine values. - **A committed `mono.env.ts` module** — an `env` object shared across the app. For non-secret values (like an API base URL) the host and its remotes all consume. A base URL doesn't need hiding, so declare it in [`mono.env.ts`](#config-env-object-non-secret-values) and read it with `monoEnv()` / `resolveEnv()` instead of pushing a `.env` a dev might forget. ## File layout The `.mono/apps/` folder is produced by [Sync](./sync). Each app brings its own env file, alongside the root env files: ``` mono-vue-remote/ ├── .mono/ │ └── apps/ │ └── mono-host/ │ └── .env.dev # app env (overrides root) ├── .env.dev # root env (loaded first) ├── .env └── package.json ``` ## How it loads mono-env loads env files in order, and **later files override earlier ones**: 1. **Root** — the file you pass with `-e`, resolved from the app you're running (e.g. `.env.dev`). 2. **Per app** — for every folder inside `.mono/apps/`, the file with the **same name** inside it (e.g. `.mono/apps/mono-host/.env.dev`). ::: tip Matched by file name Per-app files are matched by the **basename** of your `-e` value. `-e .env.dev` loads `.mono/apps//.env.dev`; `-e .env` loads `.mono/apps//.env`. Missing files are skipped with a warning — they don't stop the command. ::: ## Naming convention mono-env loads **every** key into the environment of the command it runs — but not every key reaches your client code. Vite only exposes variables matching the prefixes set in `vite.config.ts`: ```ts // vite.config.ts envPrefix: ['VITE_', 'MONO_'], ``` That gives two prefixes with different roles, plus everything else: | Prefix | Read with | Use for | | --- | --- | --- | | `MONO_` | `import.meta.env.MONO_*` | **The only shared vars.** Cross-app / mono-repo config exposed to the client bundle. | | `VITE_` | `import.meta.env.VITE_*` | App-local client config (standard Vite). | | *(no prefix)* | not exposed | Build/tooling-only secrets (tokens, generators). Stays in `process.env` for the running command, never shipped to the browser. | ::: tip Standard: shared = `MONO_` Treat `MONO_` as the contract between apps. Anything an app needs to read from another app — or anything the Host shares with Remotes — gets a `MONO_` prefix so it's exposed via `import.meta.env`. Keep app-private values on `VITE_`, and keep secrets prefix-less so they never end up in the client bundle. ::: ```ts // Shared, exposed to the client because of the MONO_ prefix const port = import.meta.env.MONO_NUXT_HOST_PORT ``` ## Config env object (non-secret values) Declare non-secret, per-environment values in a small **`mono.env.ts`** at the app root, keyed by `NODE_ENV`. This is the official home for shared, committed config. Unlike a `.env` file it's checked in — nothing for each dev to remember to push, and none of the flat-namespace collisions you hit when many apps' `.env` files merge: ```ts // mono.env.ts import { resolveEnv } from '@mono-lit/utility/config' export const env = { default: { API_BASE: 'https://api.dev.example.com' }, // shared fallback development: { API_BASE: 'https://api.dev.example.com' }, production: { API_BASE: 'https://api.example.com' }, } // Flattened active-environment values (`env.default` + the active NODE_ENV block). export const appEnv = resolveEnv({ env }) ``` ::: tip Why a separate file, not inline in `mono.config.ts`? Because more than the browser config reads these values — the OData codegen (`odata2ts.config.ts`) runs in a **bare Node context** and must import them too, and it **can't** import `mono.config.ts`. That file pulls in the `@mono-host` alias (unresolved in Node), `@mono-lit/devextreme` (a browser package), and the generated `DefaultService` DTO — which is `odata2ts`'s *own* output, a bootstrap cycle. `mono.env.ts` imports **only** `@mono-lit/utility/config`, so every consumer — browser and Node — can safely read one source of truth. ::: Wire it into `mono.config.ts`: pass `env` through (so it merges + is exposed) and build `fetching` URLs from `appEnv` — resolved **at load time**, so no `import.meta.env` and nothing to push in a `.env`: ```ts // mono.config.ts import { defineConfig } from '@mono-lit/utility/config' import { env, appEnv } from './mono.env' export default defineConfig({ name: 'mono-host', type: 'nuxt', // ... env, fetching: { api: { main: { type: 'odata', url: String(appEnv.API_BASE) } }, }, }) ``` Any other consumer imports `appEnv` the same way — including the Node codegen, which is exactly why the file stays alias-free: ```ts // odata2ts.config.ts import { appEnv } from './mono.env' const sourceUrl = String(appEnv.API_BASE) ``` It **merges across the whole host+remote `extends` chain** like the rest of the config — each remote can contribute values and the current app wins on conflicts. Because it merges *structurally* (not in one flat namespace like `.env`), it scales cleanly as you add apps. Read the active environment's values **at runtime** — in a component, store, or composable — with **`monoEnv()`**: ```ts import { monoEnv } from '@mono-lit/utility/runtime' monoEnv() // → the whole flattened object for the active NODE_ENV monoEnv('API_BASE') // → a single value ``` `monoEnv` merges `env.default` first, then the block matching the active `NODE_ENV` on top (the active block wins, key by key). ::: warning `appEnv`/`resolveEnv` at load time, `monoEnv()` at runtime `fetching.api[].url` is captured when `mono.config.ts` is imported — *before* mono initializes its state — so a bare `url: monoEnv('API_BASE')` there resolves to empty and the fetcher throws *"url is missing"*. Use `appEnv` (i.e. `resolveEnv({ env })`, computed in `mono.env.ts`) at load time; keep `monoEnv()` for reading **at runtime**, where state is live. Note `appEnv` at load time captures the app's own `env` — values a remote contributes via `extends` merge later, at runtime. ::: ::: tip `.env` must set `NODE_ENV` Selection is keyed on `NODE_ENV`. Follow the convention that each env file sets it — `.env.dev` → `NODE_ENV=development`, `.env` → `NODE_ENV=production`. `mono env` loads that file into `process.env` before Vite starts, so the right block is picked at build **and** in the browser (Vite statically replaces `NODE_ENV`). If `NODE_ENV` is ever absent, `monoEnv` falls back to Vite's `import.meta.env.MODE`. ::: ::: warning Scalars only, non-secret only Keep `env` values to scalars (string / number / boolean) — an array would concatenate across `extends` layers instead of overriding. And it's exposed to the browser bundle, so **never put secrets here** — those stay in prefix-less `.env` keys (see above). ::: ## package.json scripts The templates already route every command through mono-env. The relevant lines from `mono-vue` / `mono-host`: ```json { "scripts": { "postinstall": "mono sync && mono prepare", "mono:prepare": "mono prepare", "dev": "mono prepare && mono env -e .env.dev -- vite", "dev:h": "mono prepare && mono env -e .env.dev -- vite --host", "build": "mono env -e .env -- vue-tsc && mono env -e .env -- vite build --emptyOutDir", "preview": "mono env -e .env -- vite preview" } } ``` Everything after `--` is the command to run. Dev scripts use `.env.dev`; build and preview use `.env`. The leading `mono prepare` on the dev scripts regenerates `.mono/tsconfig.json` first — it's idempotent and fast, so it's safe to run every time (see [Prepare](./sync#run-sync)). ## Flags | Flag | Alias | Description | | --- | --- | --- | | `-e ` | `--env` | Env file to load. Repeatable — pass `-e` multiple times to load several. | | `-a ` | `--app` | Load only `.mono/apps/` instead of every app folder. | | `-r ` | `--app-root` | Folder to scan for apps. Defaults to `.mono/apps`. | | `--` | | Everything after this is the command to run. | Example — load env for a single app only: ``` mono env -e .env.dev -a mono-host -- vite ``` ## Injected variables mono-env also exposes which app(s) it loaded, so your command can read them: | Variable | When | Value | | --- | --- | --- | | `MONO_APP_NAME` | one app loaded | the app folder name (e.g. `mono-host`) | | `MONO_APP_DIR` | one app loaded | absolute path to that app folder | | `MONO_APP_NAMES` | multiple apps loaded | comma-joined list of app names | ## Multiple apps When no `-a` is given and `.mono/apps/` has more than one folder, mono-env loads them all. Because each app's env layers on top of the previous one, keys with the same name collide — the last app wins. ::: warning Use unique keys per app If two apps both define `MONO_API_URL`, whichever loads last overrides the other. Since shared vars use the `MONO_` prefix, keep them unique per app — e.g. `MONO_NUXT_HOST_API_URL`, `MONO_NUXT_REMOTE_API_URL` — or scope each run to one app with `-a`. ::: See [Sync](./sync) for how the `.mono/apps/` folder gets populated. --- URL: "https://mono-libs.netlify.app/repo/getting-started" LLMS_URL: "https://mono-libs.netlify.app/repo/getting-started.md" --- # Getting Started Mono-repo is a way to build a large-scale, modular front-end on top of the Vue ecosystem. The goal is a maintainable, clean, complex project that takes minimum effort to grow. ## Concept Vue gives every project the same predictable shape: - `src/pages` — routing - `src/layouts` — layouts Inside a layout you usually find the same generic pieces: **Sidebar**, **Navbar**, **Login**, **Logout**, **Middleware**. Every normal website needs them. Mono-repo makes this simple. Those generic pieces live once in the **Host**, and every **Remote** can use them without rebuilding. A **Remote** only adds its own modules. It does not re-create Login, Logout, or any of the generic things — the Host already handles all of that. Because of this modular concept, the Host can have many Remotes, and all of them live inside the Host. Think about a house that have many rooms. A Host can be a **Vue** app or a **Nuxt** app — and the **Host and its Remote must have the same framework**: a Vue Host takes Vue Remotes, a Nuxt Host takes Nuxt Remotes. Joining a Nuxt Host with a Vue Remote is still possible, but it is a **risky hybrid** outside the standard. See [Setup](./setup) for how each kind is wired. ## Visual Example One **Host** owns the shell; each finance module plugs in as its own **Remote**: ```mermaid graph TD Host["🏠 Host — owns the shell
Sidebar · Navbar · Login · Logout · Middleware"] Host --> Budget["📊 Budgeting"] Host --> Invoice["🧾 Invoicing"] Host --> Payroll["💰 Payroll"] Host --> Ledger["📒 General Ledger"] Host --> Reports["📈 Financial Reports"] ``` **Host** — owns the shell of the app. ``` host/ └── src/ ├── pages/ # login, logout, etc. ├── layouts/ # sidebar, navbar, etc. └── ...etc/ ``` > A **Nuxt** Host uses `app/` instead of `src/` (same folders inside). See [Setup](./setup). **Remote** — just adds modules, for example a Budget module. ``` remote/ └── src/ ├── pages/ # budget module └── ...etc/ ``` ## Install You don't build a Host or a Remote from scratch — download a template, install, done. ### Run it Inside each folder you downloaded — the Host and the Remote: ```sh pnpm i pnpm mono:sync ``` That's it — the template already ships every dependency it needs. Next, head to [Setup](./setup) to wire your Host and Remote. For the UI components and theming, continue with [Mono-UI → Getting started](/ui/getting-started) and [Theme](/ui/theme). --- URL: "https://mono-libs.netlify.app/repo/mock-api" LLMS_URL: "https://mono-libs.netlify.app/repo/mock-api.md" --- # Mock API Sometimes the backend isn't ready, or you want a demo that anyone can click through without a server behind it. Mono ships a **mock backend that lives in the browser's IndexedDB**. You declare a schema in `mono.config.ts`, and every fetching call whose URL matches that schema is answered locally — the request never leaves the page. Because there is no server, there is no port to pick, no CORS to configure, and nothing extra to start. The same code runs in dev and in a static production build, it works offline, and each visitor gets their own private copy of the data. Every app declares its own schema, and they all merge into one store, so a host and its remotes can each bring their own mock data without stepping on each other. ## Quick start Add a `mockIndexedDB` block to your `mono.config.ts`. The key of `schema` is a **base-url** — a name you invent — and under it you list your entities: ```ts import { defineConfig } from '@mono-lit/utility/config' export default defineConfig({ name: 'flow-app', type: 'vue', apps: [], mockIndexedDB: { dbName: 'flow-app-mock', version: 1, schema: { 'flow-mock': { users: { fields: { Id: 'number|primary', Name: 'string', }, }, }, }, }, }) ``` Now fetch it. Put the base-url in the call's URL and the request is served from IndexedDB: ```ts import { monoFetchOdata } from '@mono-lit/utility/fetching' const { data } = await monoFetchOdata({ url: '/flow-mock/users', type: 'data', }) ``` That's it — nothing to start, nothing to configure. ## The schema Each field is declared with a small string DSL, `'|'`: - **type** — `number`, `string`, `boolean`, `date`, `object` or `array` - **modifier** — `primary`, `foreign`, or a relation Exactly one field must be `primary`. `mono db validate` will tell you if you forget. ### Relations A relation is written `object|A->B:C` or `array|A->B:C`, and it always means the same thing: > **`A->B:C` = "rows of B where `B[C]` equals `row[A]`"** `object` gives you the first match, `array` gives you all of them. So a one-to-many belongs on the **parent**, and a many-to-one on the **child**: ```ts users: { fields: { id: 'number|primary', name: 'string', cars: 'array|id->cars:userId', // parent -> its children }, }, cars: { fields: { id: 'number|primary', userId: 'number|foreign', user: 'object|userId->users:id', // child -> its parent }, }, ``` It's easy to put the `array` relation on the wrong side. `cars: { users: 'array|userId->users:id' }` is *syntactically* fine, but it reads "this car has many users" — which is not what you meant. Relations are **virtual**. They are never stored as columns; they are materialised only when you ask for them with `$expand`, or when a filter walks them. ## Seed data Entities with no explicit seed are **generated** — deterministically, so the same rows come back on every reload and a failing test reproduces. Tune it with `seedCount` (rows per entity, default 10) and `seedRandom` (the RNG seed). Parents are generated before children, and every foreign key is pointed at a **real** parent row, so `$expand` actually returns something. The generator is fine for `users`/`orders`-shaped data. It is useless the moment an app *parses* what it reads — an enum-like column (`Type: 'start' | 'approver' | 'end'`), an icon class, a serialized JSON blob. Random strings there make the page unusable. For those, give the entity a `seed` and it wins over the generator: ```ts import nodesJson from './src/datas/mock/nodes.json' nodes: { fields: { Id: 'number|primary', Name: 'string', Type: 'string', Icon: 'string', }, seed: nodesJson, }, ``` Seed fixtures must be **importable at build time** (a literal, or an imported JSON module). Fetching them at runtime would defeat the whole point — there is no server to fetch them from in a static build. ## How a call reaches the mock The URL must carry the base-url. There are two ways to do that. **Inline**, which is the simplest: ```ts await monoFetchOdata({ url: '/flow-mock/users', type: 'data' }) ``` **Or through a named entry**, by pointing `fetching.api` at the base-url and selecting it with `configBaseUrl`: ```ts fetching: { api: { flowOdata: { type: 'odata', url: 'flow-mock' }, }, }, ``` ```ts await monoFetchOdata({ configBaseUrl: 'flowOdata', url: '/users', type: 'data' }) ``` Both resolve to `flow-mock/users`. The second is worth the extra line when you expect to move onto a real backend later — see the last section. What you cannot do is leave the base-url out entirely. `url: '/users'` matches no schema, so the call falls through to the real fetcher and throws *"no odata base url"*. That's deliberate. Every app's `mockIndexedDB.schema` is **merged into one store** (see [Multiple apps](#multiple-apps)), so two apps can each declare a `users` entity. The base-url is what keeps them apart. ## Querying The mock speaks a practical subset of OData v4, parsed properly — not pattern-matched — so precedence, parentheses and nesting behave the way they do on a real service. `$filter` supports: - comparisons `eq ne gt ge lt le`, `and` / `or` / `not`, and parentheses - `contains`, `startswith`, `endswith`, `tolower`, `toupper`, `trim`, `length`, `concat`, `indexof`, `substring` - `year`, `month`, `day`, `hour`, `minute`, `second` — and unquoted ISO date literals, compared as instants - `Field in (1,2,3)` - navigation paths — `PostBudget/Nama eq 'X'` - lambdas — `Detail/any(d: d/Bulan eq 3)` and `Detail/all(...)` - collection counts — `Detail/$count gt 0` Alongside it: `$select`, `$orderby`, `$top`, `$skip`, `$count`, `$expand` and `$apply`. A filter can walk a relation even when you never expanded it — the mock joins it on demand. ### Nested `$expand` `$expand` takes options inside the parens, and they are applied to the **children**, not ignored: ```ts await monoFetchOdata({ url: '/api/Header', type: 'data', params: { $expand: "Approval($select=Id;$expand=Step($select=ActionType);$filter=Status eq 'Menunggu';$top=1)", }, }) ``` That returns the one pending approval, with only the fields you asked for. `$select`, `$expand`, `$filter`, `$orderby`, `$top` and `$skip` all work, and nesting can go more than one level deep. ### `$apply` Grouping and aggregation work as a transformation pipeline, with segments separated by `/`: ``` $apply=filter(Price gt 10)/groupby((Category),aggregate(Price with sum as Total)) ``` Supported: `filter(...)`, `groupby((A,B), aggregate(...))`, a bare `aggregate(...)`, `$count as Alias`, and the methods `sum`, `average`, `min`, `max`, `count`, `countdistinct`. `groupby` can group by a navigation path (`groupby((PostBudget/ParentName))`). One rule is worth internalising, because getting it backwards gives you right-looking numbers over the wrong rows: - **`filter(...)` inside `$apply` runs *before* the grouping.** - **A top-level `$filter` runs *after*** — it filters the aggregated rows (`$filter=Total gt 500`). `@odata.count` follows the same logic: after `$apply` it counts the **groups**, not the source rows. ## DevExtreme Grids and select boxes work without any special handling. `loadOptions` (`filter`, `sort`, `skip`, `take`, `select`, `expand`, `requireTotalCount`) is translated into the same query engine, so paging, filtering and sorting really happen instead of the grid quietly receiving the whole table. Grouping is answered in DevExtreme's own shape — `{ key, items, count }`, with `groupSummary` / `totalSummary` — and collapsed groups return `items: null` with a correct `count`. A raw `calculateFilterExpression` string is passed through untouched, so this keeps working: ```ts calculateFilterExpression(filterValue) { return [`Detail/any(d: contains(tolower(d/KodeDept), '${filterValue}'))`] }, ``` ## Writing data All four verbs work. - **`POST`** inserts and returns `201`. If you don't supply the primary key, one is assigned. - **`PUT`** **replaces** the row (a field you omit is gone afterwards) — real OData semantics. - **`PATCH`** **merges** (an omitted field survives). - **`DELETE`** removes the row. The key is looked for in three places, in order: the **url** (`/api/users(1)` or `/api/users/1`), then `payload.keyValue`, then the body's own primary key. So the idiomatic @mono-lit/utility write works as-is: ```ts await monoFetchOdata({ url: '/flow-mock/flows', method: 'PUT', type: 'datasource', payload: { data, keyValue: 12, keyName: 'Id' }, }) ``` ### Deep insert If a field in the body matches an **`array` relation**, its rows are created in the child entity set with the foreign key pointed at the new parent — exactly as a real OData deep insert does. They are *not* stored as a blob column on the parent: ```ts await monoFetchOdata({ url: '/api/Header', method: 'POST', type: 'datasource', payload: { data: { Nama: 'Projek A', BudgetAlokasi: [{ NamaActivity: 'Activity 1' }, { NamaActivity: 'Activity 2' }], }, keyName: 'Id', }, }) ``` Afterwards, `GET /api/Alokasi` returns both children, and `$expand=BudgetAlokasi` brings them back on the parent. ## Every fetcher works The mock sits behind the whole fetching surface, so nothing about how you call it changes: - **`monoFetchOdata`** — `type: 'data'` runs the query and returns the **array**; `type: 'datasource'` returns a DevExtreme `DataSource`. - **`monoCreateFetcher(...).response()`** — returns `{ dataSource }` as usual. - **`monoFetch`** — plain REST, including path-style keys (`/api/users/1`). A `JSON.stringify`'d body is parsed for you. `options` (the DevExtreme `DataSourceOptions` shape — `select`, `filter`, `sort`, `expand`, `paginate`, `pageSize`) is honoured on every one of them, and raw `$`-params win over `options` when both are given. ## Managing the store at runtime Because the data lives in the browser, the store is managed from the browser: ```ts import { monoMockDb } from '@mono-lit/utility/fetching' const mock = monoMockDb() await mock?.reset() // wipe and re-seed const dump = await mock?.export() // every table, as plain JSON await mock?.import(dump) // put it back ``` `export()` is the easy way to turn generated rows into fixtures: dump them, paste them into an entity's `seed`. ## The CLI `mono db` covers everything that can be checked without a browser: ```bash mono db validate # parse every schema, report bad fields/relations mono db preview --entity users # print the rows the generator would produce mono db export --out seed.json # write generated rows to a file ``` `validate` exits non-zero on a bad schema, so it works in CI. There is deliberately **no `mono db serve`**. The store is the browser's IndexedDB — there is nothing for a Node process to listen on, and nothing for it to read either. That is why `reset` and `export` at runtime are the browser APIs above, not CLI commands. ## Multiple apps Schemas merge across apps on their own. `mockIndexedDB.schema` is a plain object, so a host and its remotes each contribute their own base-url and they all end up in one IndexedDB — no coordination needed. One thing to watch: **keep everything inside `mockIndexedDB` a keyed object.** Arrays are *concatenated* when configs merge and are never de-duplicated, so an array option would silently double up once two apps declared it. ## Limits and gotchas **IndexedDB does not exist during SSR or prerendering.** The mock is browser-only. On a Nuxt host, mark a page that uses it client-only, or `nuxt build` will fail while prerendering: ```ts // nuxt.config.ts routeRules: { '/flow': { ssr: false }, }, ``` **Private browsing** may restrict or memory-back IndexedDB. The store fails to open, requests return `503`, and lists render empty — a deployed demo opened in incognito can look broken. **Bumping `version` wipes the store** and re-seeds it. That is intended for a schema change, but it is destructive: anything the user saved is gone. **Not supported**, because nothing in our apps uses them: `$batch`, `$search`, `substringof`, composite or GUID keys, and the arithmetic operators (`add` / `sub` / `mul` / `div`). Anything unsupported throws a clear error rather than silently returning wrong data. ## Moving to a real backend Nothing about the calls has to change. Declare a real `fetching.api` entry and select it with `configBaseUrl`: ```ts fetching: { api: { myOdata: { type: 'odata', url: String(import.meta.env.MONO_APP_ODATA_BASE_URL), oDataService: DefaultService, }, }, }, ``` ```ts await monoFetchOdata({ configBaseUrl: 'myOdata', url: '/users', type: 'data' }) ``` The URL no longer matches a mock schema, so the same call goes to the network. Keep the `mockIndexedDB` block if you want the mock available for tests or offline demos — it only ever intercepts URLs that match one of its base-urls. --- URL: "https://mono-libs.netlify.app/repo/provide-inject" LLMS_URL: "https://mono-libs.netlify.app/repo/provide-inject.md" --- # Provide and Inject You can communicate between Remote and Host, or Host and Remote, using the provide-and-inject concept. It can send a string, number, object, or array — and it stays reactive. Both sides share one reactive payload through a common key — either side can provide it and either side can inject it: ```mermaid graph LR Host["🏠 Host"] <-->|"monoProvide / monoInject"| Data["🔑 Shared reactive state
key: 'message:send'"] Data <-->|"monoProvide / monoInject"| Remote["📦 Remote"] ``` Let's say this is a Remote that needs to send data — use `monoProvide`: ```vue ``` On the Host side, you can receive the state as long as it shares the same key: ```vue ``` This case is kind of unique and rare. For now, the feature already using it is sending menu data from Remote to Host. --- URL: "https://mono-libs.netlify.app/repo/resolvers" LLMS_URL: "https://mono-libs.netlify.app/repo/resolvers.md" --- # Resolvers A **resolver** is a host-side stopgap fix. When a remote app has a bug or isn't ready yet and it breaks the host, the host doesn't wait for the upstream fix — it drops a small file in a `resolvers/` folder, wires it in, and **deletes it once the remote is fixed upstream**. Resolvers live only in the host; the remote stays untouched. ## Two kinds Where a resolver goes depends on what it fixes. - **Build-config resolver** — a **root-level `resolvers/`** folder, next to the host config. It fixes things at build/resolution time (redirect a broken remote import, patch an alias, tweak `optimizeDeps`) and is imported into the host config: `nuxt.config.ts` on a Nuxt host, `vite.config.ts` on a Vue host. This is the common case. - **Runtime resolver** — a `resolvers/` folder inside the src dir, for a fix that is itself runtime code (a composable, store, or component that patches remote behavior at runtime). It lives in **`app/resolvers/`** on a Nuxt host (srcDir is `app/`) and **`src/resolvers/`** on a Vue host or remote (srcDir is `src/`). ## Rules - **Not auto-imported.** Unlike `composables/` and `stores/`, the `resolvers/` folder is never scanned for auto-imports. Always import a runtime resolver **explicitly, via the host app alias `@mono-host`** — so every fix stays visible and easy to find and delete. - **Label it as a stopgap.** Add a comment at the top saying which remote issue it works around. - **Document the real fix.** Always write a detailed comment explaining **how to fix it properly in the remote** — the actual change the remote needs — so whoever fixes the remote later has the instructions right there. - **Delete when fixed.** Remove the resolver file *and* its wiring the moment the remote is fixed upstream — resolvers are meant to disappear. ## Example A build-config resolver on a Nuxt host that redirects a broken component from the `flow-app` remote to a host copy, until the remote fixes it. `resolvers/flow-app.ts` (root, next to the host config): ```ts import type { Plugin } from 'vite' import { fileURLToPath } from 'node:url' // Stopgap: the flow-app remote ships a broken CodeMirror.vue. // Redirect its import to a host copy until the remote fixes it upstream. // // HOW TO FIX IN THE REMOTE (then delete this resolver + its wiring): // In mono-vue-remote, src/components/CodeMirror.vue must register the SQL // language: `import { sql } from '@codemirror/lang-sql'` and add `sql()` to the // editor `extensions`. Once that ships, the host copy is no longer needed. const hostCopy = fileURLToPath( new URL('../app/overrides/FlowCodeMirror.vue', import.meta.url), ) export function flowAppCodeMirrorOverride(): Plugin { return { name: 'mono-flow-codemirror-override', enforce: 'pre', resolveId: (id) => id === '@flow-app/components/CodeMirror.vue' ? hostCopy : null, } } ``` Wire it in `nuxt.config.ts` (a Vue host does the same in `vite.config.ts`): ```ts import { flowAppCodeMirrorOverride } from './resolvers/flow-app' export default defineNuxtConfig({ vite: { plugins: [flowAppCodeMirrorOverride()] }, }) ``` A **runtime** resolver is wired differently — it is not auto-imported, so you import it explicitly with the `@mono-host` alias where you use it: ```ts // app/resolvers/patch-remote-user.ts (src/resolvers/… on a Vue host) import { patchRemoteUser } from '@mono-host/resolvers/patch-remote-user' ``` ::: tip When the remote fix lands, delete `resolvers/flow-app.ts` and remove its line from the config. A resolver that outlives its remote bug is just dead weight. ::: --- URL: "https://mono-libs.netlify.app/repo/setup" LLMS_URL: "https://mono-libs.netlify.app/repo/setup.md" --- # Setup The mono ecosystem has two roles: a **Host** and one or more **Remotes** (see [Getting Started](./getting-started)). The Host owns the shared shell; a Remote adds its own pages and plugs into it. A **Host is Vue or Nuxt** — and the **Host and its Remote must have the same framework**. A Vue pair (Vue Host + Vue Remote) is joined by mono's own merge; a Nuxt pair (Nuxt Host + Nuxt Remote) by Nuxt's own layer system. Those two choices are the only things that change between setups. ::: warning The hybrid pairing — possible, but at your own risk Joining a **Nuxt Host** with a **Vue Remote** is still possible: mono's compat layer (`mono.nuxt()`) rewrites the host's Nuxt code so the Remote's Vite build can run it, so nothing blocks the combination. It is **outside the standard** — the Remote ships as a client-rendered island inside a server-rendered shell, and the seams that compat layer papers over (SSR, layouts, routing, state) remain your risk. Prefer the same-framework pairing; take the hybrid only when you knowingly accept those risks. ::: ## Build config This page covers one file per app: `vite.config.ts` for a Vue app, `nuxt.config.ts` for a Nuxt one. Pick your Host kind below — its file opens, then the Remote that pairs with it. The [templates](./getting-started#install) already ship these. Nothing in these files says whether an app is a Host or a Remote, or which other app it federates. That is declared in [`mono.config.ts`](./config) — the build config only wires mono into the bundler. ## Next steps - [Config](./config) — `mono.config.ts`: the `type` field, cookies, JWT, and the deploy menu. - [Sync](./sync) — how the other app is pulled into `.mono/apps/`. - [Environment](./env) — secrets and the shared `MONO_` prefix. - [Template Rules](../ai/template) — the full rules the AI follows in a Host or Remote. --- URL: "https://mono-libs.netlify.app/repo/sync" LLMS_URL: "https://mono-libs.netlify.app/repo/sync.md" --- # Sync The Host and the Remote live in separate repositories. **@mono-lit/utility** keeps them in step, and both the [Mono Host](https://github.com/mono-lit/templates/tree/main/vue-host) and the [Mono Remote](https://github.com/mono-lit/templates/tree/main/vue-remote) (in the `mono-lit/templates` monorepo) ship with it installed. Sync flows **both ways**, through GitHub. Neither side talks to the other directly — each one pushes to GitHub, and the other picks the change up on its next sync: ```mermaid graph LR R["📦 Remote
pushes update"] -->|git push| GH["🐙 GitHub"] GH -->|"pnpm mono:sync"| H["🏠 Host
gets the new module"] H -->|"push shell update
layout · login · navbar"| GH2["🐙 GitHub"] GH2 -->|"pnpm mono:sync"| R2["📦 Remote
gets the shell update"] ``` A Remote pulls in shell updates from the Host; the Host pulls in each Remote's new modules. ::: tip Working with the repos side by side? Put every app in one repository as sibling folders and connect them by `apps[].path` — no sync round-trip, and the host hot-updates when a remote changes. See [Mono-Lith](/lith/getting-started). ::: ## Setup Sync Both templates use these files: ``` mono-vue-remote/ ├── .mono/ │ ├── apps/ # synced remotes land here │ └── tsconfig.json # generated path aliases (see Prepare) ├── mono.config.ts ├── package.json ├── .env.dev └── .env ``` Everything mono generates lives under one gitignored `.mono/` folder. You never edit it by hand. ### mono.config.ts Lists the apps to sync. On a Remote, list your Host here: ```ts import { defineConfig, JWTCompleteTokenTypes } from "@mono-lit/utility/runtime"; export default defineConfig({ name: 'mono-remote', apps: [ { name: 'mono-host', url: 'https://github.com/mono-lit/templates/tree/main/vue-host', envToken: 'MONO_TOKEN' } ] }); ``` The `url` carries the ref directly, GitHub-style: - `…/mono-vue-host` — the `main` branch - `…/mono-vue-host/tree/v4.0.7` — a tag - `…/mono-vue-host/tree/feat/layout-program` — a branch (slashes are fine) - `…/mono-vue-host/tree/deac44a955ac63981e6bae705f5df3f2d61dcf0f` — a commit SHA ### .env and .env.dev `envToken` names a [GitHub token](https://github.com/settings/tokens) kept in `.env` or `.env.dev`: ``` MONO_TOKEN=YOUR_GITHUB_TOKEN ``` It is **optional** — if everyone who syncs the app has been invited to its repo, `mono sync` uses your own git credentials and never needs a token. ### package.json The sync script: ```json { "scripts": { "mono:sync": "mono sync && mono prepare", "mono:prepare": "mono prepare", "postinstall": "mono sync && mono prepare" } } ``` ## Run Sync ``` pnpm mono:sync ``` Each app in `mono.config.ts` is downloaded into `.mono/apps/`. `mono prepare` then regenerates `.mono/tsconfig.json`, so the new app's `@` alias is available to TypeScript right away. --- URL: "https://mono-libs.netlify.app/repo/template-changelog" LLMS_URL: "https://mono-libs.netlify.app/repo/template-changelog.md" --- # Template Changelog Changes to the starter templates, grouped by change. Each shows the commit and the exact lines to remove (red) / add (green). ## One `vite.config.ts` for Host and Remote · 2026-08-23 Both templates used to hand-write their entire mono plugin block, and the two files differed in ways that looked meaningful but mostly were not. They now ship the **same file**: the `.options()` builders plus **`mono.vite()`**, with one new `mono.config.ts` field — **`template`** — carrying the only difference that turned out to be real. ::: tip Nothing here forces a migration The long-hand style — `...mono.ecosystem([...])` spreads with `mono.plugin` last — still works unchanged, and so does the older pre-`monoRepo()` style (`monoAlias()` / `getMonoConfig()` / `monoEcosystem()` / `monoNuxtHost()`). Both were rebuilt against the current library and produce **byte-identical** output. This entry is a simplification you can adopt when it suits you, not a breaking change to chase. ::: Almost everything the two configs disagreed on was already derivable from `mono.config.ts` and from disk: | Used to be hand-written | Now | | --- | --- | | `...mono.nuxt().hostResolver()` + `extendRoute:` | derived from `apps[].type === 'nuxt'` | | the root-`index.vue` exclusion on federated pages | derived from whether this app has `pages/index.vue` | | `src/` vs `app/` dirs, `dts` paths | derived from `type` | | `composables/shared` / `stores/shared` dirs | included on both sides automatically | Auditing what was left found exactly **one** real difference — layouts. A Host renders its own `layouts/` and takes no federated ones; a Remote consumes the Host's. Nothing on disk can tell the two apart (an app with no `layouts/` looks identical either way), so that one is declared: ```diff # mono.config.ts type: 'vue', + template: 'host', // or 'remote'; omitted behaves as 'remote' ``` It is **never inherited through `extends`** — a Remote extending its Host would otherwise be told it was a Host and drop the shell it exists to consume, silently. See [Config → App role](./config#app-role-host-or-remote). ### mono-vue-remote `example-nuxt-host` · `fee69e8` The whole plugin block collapses into the `.options()` builders. You keep the real plugin imports — `vue-router` and the unplugins capture their dirs in a closure, so mono cannot inject after construction; it hands you the object to construct **with**. ```diff -export default defineConfig(async ({ mode }) => { - const mono = await monoRepo() +export default defineConfig(async ({ mode, command }) => { + const mono = await monoRepo({ command }) ``` `command` is passed so an app's dev-only `path` (a local checkout) is honoured in `serve` and ignored in `build`. Without it that is inferred from `process.argv`, which covers the CLI but not a programmatic `build()`. ```diff plugins: [ - ...mono.nuxt().hostResolver(), - VueRouter({ - routesFolder: [ - { src: 'src/pages' }, - ...mono.ecosystem('pages'), - ], - extendRoute: mono.nuxt().extendRoute(), - }), + VueRouter(mono.pages.options()), - AutoImport({ + AutoImport(mono.autoImport.options({ imports: [ /* … unchanged … */ ], - dts: 'src/auto-imports.d.ts', - dirs: [ - 'src/composables', - 'src/stores', - ...mono.ecosystem(['composables/shared','stores/shared','composables']), - ], - vueTemplate: true, - }), - Components({ - extensions: ['vue'], - include: [/\.vue$/, /\.vue\?vue/], - dts: 'src/components.d.ts', - directoryAsNamespace: true, - collapseSamePrefixes: true, - dirs: ['./src/components', ...mono.ecosystem('components')], - }), - Layouts({ - layoutsDirs: mono.ecosystem('layouts'), - defaultLayout: 'default' - }), + })), + Components(mono.components.options()), + Layouts(mono.layouts.options()), - mono.plugin, + mono.vite(), ] ``` The Nuxt-compat spread and `extendRoute` disappear because `mono-host` is already declared `type: 'nuxt'` in `apps[]`. They are not lost — `mono.vite()` adds them, and they now declare a hook-level `order: 'pre'`, so they beat `VueRouter` wherever the call sits in the array. The old "spread it BEFORE VueRouter" convention is no longer something you can get wrong. ```diff # mono.config.ts type: 'vue', + // This app CONSUMES the shared shell rather than owning it, so it takes the + // host's layouts as well as any of its own. + template: 'remote', ``` Verified: route table, `auto-imports.d.ts` and `components.d.ts` come out **identical** to the hand-written config, and the built bundle still contains zero `definePageMeta` or ``. ### mono-vue-host `main` · `bb89b27` Same file, same shape. The host-specific lines all turn out to be derivable: ```diff - VueRouter({ - routesFolder: [ - { src: "src/pages" }, - // host owns `/`, so skip each remote's root index.vue - ...mono.ecosystem('pages').map((dir) => ({ - src: dir, - exclude: ['*/index.vue'], - })), - ] - }), + VueRouter(mono.pages.options()), - AutoImport({ + AutoImport(mono.autoImport.options({ imports: [ /* … unchanged … */ ], - dts: true, - dirs: [ - "./src/composables/**", - "./src/stores/**", - ...mono.ecosystem(['composables', 'stores']), - ], - vueTemplate: true, - }), - Components({ - dirs: ["./src/components", ...mono.ecosystem('components')], - dts: true, - directoryAsNamespace: true - }), - //@ts-ignore - Layouts({ - // The host ships its own layout shell — no remote layouts here. - layoutsDirs: 'src/layouts', - defaultLayout: 'default' - }), + })), + Components(mono.components.options()), + Layouts(mono.layouts.options()), - mono.plugin, + mono.vite(), ``` ```diff # mono.config.ts type: 'vue', + // This app OWNS the shared shell, so it renders its own `src/layouts` and + // takes none from the apps it federates. + template: 'host', ``` The federated-page exclusion goes away because this host ships `src/pages/index.vue`, so mono can see that it owns `/` and excludes each federated app's root page on its own. (`mono-vue-remote` has no `index.vue`, so it correctly keeps the Host's `/`.) The `//@ts-ignore` above `Layouts` goes with it. **That `Layouts` line was also a latent bug.** `layoutsDirs` was a bare **string**, which silently switches `vite-plugin-vue-layouts-next` to its `ClientSideLayout` implementation — a different code path with a single hardcoded `import.meta.glob` that cannot see federated dirs at all. It was harmless only because this host federates nothing today. `mono.layouts.options()` always returns an array. Two migration notes, both specific to a Host on the old defaults: - **The generated `.d.ts` files move from the repo root to `src/`** (`dts: true` → mono's `src/auto-imports.d.ts`). Both were tracked at the root; delete them in the same commit, or TypeScript sees two sets of the same globals. `tsconfig.json` needs no change if it already has `include: ["**/*"]`. - **`mono.autoImport.options()` scans `composables/shared` and `stores/shared` in *this* app**, not just federated ones. That was a gap in mono, fixed for this migration: a Host keeping code under `src/stores/shared/` was reaching it only through its own `"./src/stores/**"` glob, so adopting mono's defaults would otherwise have dropped `useAuthStore`, `useHostMenuStore` and `useHostHelper` — silently, since a missing auto-import only errors at the use site. Verified by a clean A/B — both configs built from scratch with the generated files deleted first, so neither inherits stale entries: **648 auto-import lines either way, zero symbols gained or lost, zero components renamed** by `collapseSamePrefixes`. `vue-tsc` reports the same three pre-existing errors and no new ones. ::: warning Delete the generated files before comparing The committed `auto-imports.d.ts` in both templates had drifted — it still declared symbols from apps the repo no longer federates and from files that were since deleted. Worse, `unplugin-auto-import` **carries existing entries forward** when its `dts` file already exists, so a fresh build does not clear them. If you diff your new output against the committed file you will see losses that are not real. Delete it first. ::: ::: tip Mixing the two styles is safe Adding `mono.vite()` to a config that already wires the plugins by hand contributes **nothing** — each manual call marks that ecosystem as yours, so it fills only the gaps. `template` does not affect the hand-wired path either: when you pass the dirs, mono does not second-guess you. That makes this adoptable one plugin at a time. ::: ## Simplify Config · 2026-08-02 The mono wiring scattered through `vite.config.ts` is consolidated under one `await monoRepo()` call — the Vite twin of `@mono-lit/utility/nuxt`. The `monoAlias` + `getMonoConfig` + `activeApps` block at the top of `defineConfig(async …)` and every repeated `monoEcosystem({ dirname, apps: activeApps, subs })` call site collapse into the one `mono` handle, alongside the nuxt-host compat helpers. (`mono.plugin`'s alias / `__MONO_CONFIG_EXPOSE__` / `server.fs.allow` / dep-dedup wiring is documented separately.) ### mono-vue-remote `example-nuxt-host` — `monoRepo()` lands in `5e5923df`, the nuxt-host helpers in `e9f62e89`. `mono.plugin` stays registered **last** to wire `resolve.alias` / `__MONO_CONFIG_EXPOSE__` / `server.fs.allow` / dep dedup from the same single config load. **`mono.ecosystem(subs)` — dir discovery.** The whole extends-aware setup used to be hand-written in every host: ```diff -import { monoEcosystem } from '@mono-lit/utility' -import { getMonoConfig, monoAlias } from '@mono-lit/utility/config/node' -import { resolveExtendsAppNames } from '@mono-lit/utility/config' +import { monoRepo } from '@mono-lit/utility/vite' ``` ```diff -const alias = monoAlias({ dirname: fileURLToPath(new URL('.', import.meta.url)) }) -const monoConfig = await getMonoConfig({ jitiOptions: { alias } }) -const hasExtends = monoConfig.extends != null -const activeNames = resolveExtendsAppNames(monoConfig) -const activeApps = hasExtends - ? (monoConfig.apps ?? []).filter((a) => activeNames.includes(a.name)) - : (monoConfig.apps ?? []) +const mono = await monoRepo() ``` `monoRepo()` loads `mono.config.ts` (c12/jiti, taught the alias map) and resolves the `extends`-active apps **once**; `mono.ecosystem(subs)` is then a one-liner over those apps — type-aware, so a `nuxt` remote resolves to `app/_{` and a `vue`
remote to `src/_{`. Each of the four call sites shrinks to it (the `dirname` /
`apps` args are baked in):

```diff
// pages
- ...monoEcosystem({ dirname: __dirname, apps: activeApps, subs: 'pages' })
+ ...mono.ecosystem('pages')
// composables / stores
- ...monoEcosystem({ dirname: __dirname, apps: activeApps, subs: ['composables/shared','stores/shared','composables'] })
+ ...mono.ecosystem(['composables/shared','stores/shared','composables'])
// components
- ...monoEcosystem({ dirname: __dirname, apps: activeApps, subs: ['components'] })
+ ...mono.ecosystem('components')
// layouts
- layoutsDirs: monoEcosystem({ dirname: __dirname, apps: activeApps, subs: 'layouts' }),
+ layoutsDirs: mono.ecosystem('layouts'),
+ // ← last
+ mono.plugin,
```

**`mono.nuxt()` — nuxt-host compat helpers (only when the remote is a Nuxt app).**
`monoNuxtHost()` and `monoExtendRoute()` — the helpers a Vue/Vite host needs when a
federated **remote is a Nuxt app** — used to be standalone imports from
`@mono-lit/utility/vite`. They now hang off the same `mono` handle as `mono.nuxt()`:

> **Only for a Nuxt remote.** Add these when the app you extend (`extends`) is a
> **Nuxt** host (its source lives under `app/`, its pages declare `definePageMeta`,
> its layouts use ``). A **Vue** host federation (e.g. `example-vue-host`)
> needs none of this — its pages use `definePage` natively and its layouts already
> render `` — so it omits `mono.nuxt()` entirely.

- `mono.nuxt().hostResolver()` — the `Plugin[]` (= `monoNuxtHost()`) that rewrites
unsupported Nuxt code for Vue: strips the `definePageMeta({…})` macro from
`.mono/apps/*.vue`, rewrites a remote layout's default `` →
`` (so `setupLayouts`' nested routes render the page), and defines
`import.meta.server`/`import.meta.client` for federated code that branches on
them. Spread **before** `VueRouter()` so the rewrite runs first.
- `mono.nuxt().extendRoute()` — the `VueRouter({ extendRoute })` callback (=
`monoExtendRoute()`) that injects `{ layout, title }` parsed from a synced
remote page's source, so `setupLayouts` wraps it. Host pages (which use
`definePage`, read natively by vue-router) are skipped.

```diff
-import { monoNuxtHost, monoExtendRoute } from '@mono-lit/utility/vite'
+// (now on the `mono` handle above — Nuxt remote only)
```

```diff
plugins: [
// Nuxt remote only — omit these two for a Vue host federation.
- ...monoNuxtHost(),
+ ...mono.nuxt().hostResolver(),
VueRouter({
routesFolder: [...],
- extendRoute: monoExtendRoute(),
+ extendRoute: mono.nuxt().extendRoute(),
}),
```

The standalone `monoNuxtHost` / `monoExtendRoute` exports stay for back-compat;
`mono.nuxt()` is the public surface going forward. Both still take the same options
(`appsMarker`, `defineImportMeta`) if you need to override the `/.mono/apps/` marker.

### mono-vue-host

`main` · `bc5d914`. The host shell gets the same `monoRepo()` treatment. It's a
pure **Vue** host (no Nuxt remote), so `mono.nuxt()` is **not** used — only
`mono.ecosystem(...)` for dir discovery and `mono.plugin` for the alias / define /
server.fs wiring. The host ships its **own** layout shell, so `Layouts` keeps
`layoutsDirs: 'src/layouts'` (no remote layouts). Per-page `exclude: ['*/index.vue']`
on the federated routes is preserved — the host owns `/`, so each remote's root
`index.vue` is skipped to avoid clobbering it.

```diff
-import { monoEcosystem } from '@mono-lit/utility'
-import { getMonoConfig, monoAlias } from '@mono-lit/utility/config/node'
-import { resolveExtendsAppNames, type MonoConfig } from '@mono-lit/utility/config'
+import { monoRepo } from '@mono-lit/utility/vite'
```

```diff
-declare global {
- const __MONO_CONFIG_EXPOSE__: Pick & { … }
-}
-const alias = monoAlias({ dirname: fileURLToPath(new URL('.', import.meta.url)) })
-const monoConfig = await getMonoConfig({ jitiOptions: { alias } })
-const hasExtends = monoConfig.extends != null
-const activeNames = resolveExtendsAppNames(monoConfig)
-const activeApps = hasExtends
- ? (monoConfig.apps ?? []).filter((a) => activeNames.includes(a.name))
- : (monoConfig.apps ?? [])
+const mono = await monoRepo()
```

```diff
// pages — host owns `/`, skip each remote's root index.vue
- ...monoEcosystem({ dirname: __dirname, apps: activeApps, subs: 'pages' }).map((dir) => ({
- src: dir, exclude: ['*/index.vue'],
- })),
+ ...mono.ecosystem('pages').map((dir) => ({ src: dir, exclude: ['*/index.vue'] })),
// composables / stores
- ...monoEcosystem({ dirname: __dirname, apps: activeApps, subs: ['composables', 'stores'] }),
+ ...mono.ecosystem(['composables', 'stores']),
// components
- ...monoEcosystem({ dirname: __dirname, apps: activeApps, subs: ['components'] }),
+ ...mono.ecosystem('components'),
// ← last
+ mono.plugin,
```

The inline `define.__MONO_CONFIG_EXPOSE__`, `server.fs.allow` and `resolve.alias`
blocks all drop out (owned by `mono.plugin`); `vueDevTools()`, the `IS_SENTRY`
sourcemap flag and the commented `sentryVitePlugin` are untouched.

## Sticky Nav Fix · 2026-07-29

`` refused to stick to the top of the page: it scrolled away with the
content. The component was fine — `sticky` defaults to `true`, reflects to a
`sticky` attribute, and `mono-nav[sticky] { position: sticky; top: 0 }` applied.
The layout wrapper was the problem.

Per CSS overflow, when one axis is **not** `visible` the other computes from
`visible` to **`auto`**. So `overflow-x-hidden` on the page wrapper silently made
that `` a **scroll container**, and it — not the viewport — became the sticky
element's scrollport. Its height is content-driven (the child is `min-h-screen`),
so it never scrolls internally: the nav had zero scroll range and just rode the
document scroll away.

`overflow-x: clip` suppresses horizontal overflow exactly the same way but is not
a scroll container, so `overflow-y` stays `visible`. Both templates run
`presetWind4`, which ships the `overflow-x-clip` utility.

Measured with the real element inside this layout chain: with `hidden` the nav
moved `top 0 → -604px` over an 800px scroll (wrapper computed `hidden/auto`);
with `clip` it stayed at `top 0` (wrapper computed `clip/visible`).

`mono-vue-host` `src/layouts/home.vue` (`main` · 2100d49) and `mono-nuxt-host`
`app/layouts/home.vue` (`main` · 00662a3, `example` · fa232f0):

```diff
-
+
```

Watch for this whenever a sticky element is nested: **any** ancestor with
`overflow` set to `hidden`, `auto` or `scroll` on either axis captures it.

## UnoCSS scans federated `.mono/apps` · 2026-07-28

Federated remotes live under `.mono/apps/` at the project root. The old
`content.pipeline.include` used **relative globs** (`./.mono/apps/*/src/**`) as the
UnoCSS pipeline filter — but UnoCSS resolves those against Vite's `root`, and they
don't match the (absolute / virtual) module ids Vite actually hands it. Under
**Nuxt's Vite** it is worse than unreliable: `root` is the srcDir (`app/`), so
`./.mono/apps/**` resolves to a non-existent `app/.mono/apps` and matches nothing at
all. Either way the failure is silent — no error, just missing CSS. So federated
`.ts` data modules that carry classes (e.g. `datas/flow.ts` node-card colors) and each
remote's `mono.config.ts` menu `icon` classes were dropped → federated routes
rendered unstyled / icons missing.

Fix: anchor an **absolute** `content.filesystem` scan of `.mono/apps` (eager, so
federated classes land in `uno.css` upfront) and restore the default `include` regex,
adding a second regex that admits federated `.ts/.js` — a regex matches module ids
where a relative glob cannot. The app's **own** files keep flowing through the default
pipeline (`.vue` via the default regex, `.ts` via their `//@unocss-include` comment);
this block is scoped to `.mono/apps` only.

`uno.config.ts` in `mono-vue-host` (`main` · 29a88c8), `mono-nuxt-host` (`main` ·
3c18735, `example` already had it) and `mono-vue-remote` (`example-nuxt-host` ·
9e2db8e, `example-vue-host` · 3011a7b, `gallery-apps` · e68aa27, `memo-apps` ·
5d3380f, `refactor/ERP_CONCEPT` already had it):

```diff
+import { fileURLToPath } from "node:url";
+const monoApps = fileURLToPath(new URL("./.mono/apps", import.meta.url)).replace(/\\/g, "/");
content: {
- pipeline: { include: [
- './src/**/*.{js,ts,vue,html}',
- './.mono/apps/*/src/**/*.{js,ts,vue,html}',
- './.mono/apps/*/mono.config.ts',
- ] },
+ filesystem: [
+ `${monoApps}/*/src/**/*.{js,ts,vue,html}`,
+ `${monoApps}/*/app/**/*.{js,ts,vue,html}`,
+ `${monoApps}/*/mono.config.ts`,
+ ],
+ pipeline: { include: [
+ /\.(vue|svelte|[jt]sx|vine.ts|mdx?|astro|elm|php|phtml|marko|html)($|\?)/,
+ /[\\/]\.mono[\\/]apps[\\/].*\.(ts|js)($|\?)/,
+ ] },
},
```

Two wrinkles behind that diff. The removed `'./src/**'` glob gets **no** replacement —
the app's own files go back to UnoCSS's default include, which the first added regex
restores. And `mono-nuxt-host` had no `content` block to remove at all, only a comment
explaining why it had gone without one; that comment's diagnosis was right (a relative
glob stops matching under Nuxt's Vite) but its conclusion was to drop `content` rather
than switch to an absolute base.

Watch for this whenever a scanned path sits outside the Vite root: a relative
`content` glob resolves against that root, so it fails by matching **nothing** rather
than by erroring.

## Self-healing `pnpm i` · 2026-07-27

`postinstall` runs `mono sync && mono prepare && nuxt prepare`. The `mono sync` is
there on purpose — see "Bootstrap order" below; without it `pnpm i` cannot recover
from an empty `.mono/apps/`. After changing `mono.config.ts` `apps[]` you can still
run `pnpm mono:sync` explicitly (it uses `.env.dev`), but a plain `pnpm i` now picks
the new remote up on its own.

### mono-nuxt-host

`main` `b115033` · `example` `c4ef78d`

```diff
# package.json
- "postinstall": "mono prepare && nuxt prepare",
+ "postinstall": "mono sync && mono prepare && nuxt prepare",
```

Since pnpm auto-runs `install` before any script (verify-deps), a broken `.mono/`
makes **every** `pnpm` command fail — including `pnpm mono:sync`, the one that would
fix it. That is why `mono sync` now runs first in `postinstall`.

To break the deadlock by hand, bypass pnpm:

```bash
node node_modules/@mono-lit/utility/dist/mono.mjs sync # reads .env itself via dotenv
```

## Picking between non-safe and safe env · 2026-07-26

Decide what belongs in `.env` vs the config. **Safe (non-secret)** values — API
base URLs, the public Picsum endpoint — don't need hiding, and in a federation the
host consumes its remotes' config, so they go in a committed, shared **`env`
object**. **Non-safe (secret)** values — GitHub PATs, Sentry token/DSN — stay in
`.env` only. The base URLs move into a standalone **`mono.env.ts`** (read via
`resolveEnv`) imported by every consumer (`mono.config` fetching, `odata2ts`
codegen, and — on the Nuxt host — `sentry.client.config`), so nothing breaks when
a dev forgets to push `.env`. See [Environment](./env#config-env-object-non-secret-values).

**Dev-only knobs out of `.env` too.** `PORT` and `VITE_HTTPS` are dev-server-only,
so they move to a hardcoded `const PORT` in `vite.config.ts` / `nuxt.config.ts`
(with `mkcert` forced off), and drop out of every `.env`. `mono-vue-remote`'s
`example-*` branches already did this — the rest now match.

```diff
# vite.config.ts (nuxt.config.ts uses devServer.port: PORT)
+const PORT = 2020 // 7100 on the hosts
- server: { port: Number(process.env.MONO_VUE_PORT) },
+ server: { port: PORT },
- preview: { port: Number(process.env.MONO_VUE_PORT) },
+ preview: { port: PORT + 1 },
- process.env.VITE_HTTPS == 'true' && mkcert({ … }),
+ false && mkcert({ … }),
```

```diff
# .env / .env.dev / .env.example
-VITE_HTTPS="false"
-MONO_HOST_PORT="7100" # MONO_VUE_PORT on the remote
```

Follow-up commits: `mono-nuxt-host` `e140457` (main) · `52aaf3c` (example) ·
`mono-vue-host` `7e6a90d` · `mono-vue-remote` `gallery-apps` `89565f2` ·
`memo-apps` `d0f0fa3` · `module/purchasing` `206e93a` (the `example-*` branches
already hardcoded `PORT`).

### mono-nuxt-host

`main` `0629563` · `example` `d184423`

```diff
+ // mono.env.ts (new) — single source, no @mono-host/devextreme imports
+ import { resolveEnv } from '@mono-lit/utility/config'
+ export const env = {
+ default: {
+ MONO_HOST_API_BASE_URL: 'https://dev-ppl-project.phoenix-squad.eu.org',
+ MONO_HOST_ODATA_BASE_URL: 'https://dev-ppl-project.phoenix-squad.eu.org/odata',
+ },
+ }
+ export const appEnv = resolveEnv({ env })
```

```diff
# mono.config.ts
+import { env, appEnv } from './mono.env'
...
+ env,
fetching: {
api: {
- monoHostRest: { type: 'restful', url: String(import.meta.env.MONO_HOST_API_BASE_URL) },
+ monoHostRest: { type: 'restful', url: String(appEnv.MONO_HOST_API_BASE_URL) },
```

```diff
# odata2ts.config.ts # sentry.client.config.ts does the same swap
-import dotenv from 'dotenv'
-dotenv.config()
-const sourceUrl = `${String(process.env.MONO_HOST_ODATA_BASE_URL)}`
+import { appEnv } from './mono.env'
+const sourceUrl = String(appEnv.MONO_HOST_ODATA_BASE_URL)
```

```diff
# .env / .env.dev / .env.example
+NODE_ENV="development" # ("production" in .env)
-MONO_HOST_API_BASE_URL="https://dev-ppl-project.phoenix-squad.eu.org"
-MONO_HOST_ODATA_BASE_URL="https://dev-ppl-project.phoenix-squad.eu.org/odata"
```

### mono-vue-host

`main` `41a8f92`

Same pattern with `MONO_HOST_*` vars. Consumers: `mono.config.ts` (fetching) and
`odata2ts.config.ts` (no `sentry.client.config.ts` — this host gates Sentry in
`vite.config.ts`). Base URLs removed from `.env` / `.env.dev`.

### mono-vue-remote

`example-vue-host` `90b1f8d` · `example-nuxt-host` `f9b75b0` ·
`gallery-apps` `a80ddbf` · `memo-apps` `5eb381b` · `module/purchasing` `59eb308`

Same pattern across all 5 branches with `MONO_VUE_*` vars. Per-branch specifics:

- **example-vue-host / example-nuxt-host**: the base URLs were hardcoded in
`src/datas/appConfig.ts` and selected by a `NODE_ENV`→`MODE` switch — both are
removed; `appConfig` now holds only the JWT cookie names.
```diff
# mono.config.ts
-const MODE = import.meta.env.NODE_ENV == 'development' ? 'dev' : …
- url: appConfig.api[MODE ?? 'dev'],
+ url: String(appEnv.MONO_VUE_API_BASE_URL),
```
- **gallery-apps**: also moves the public Picsum literal into `env.default`
(`PHOTOS_API: 'https://picsum.photos/v2'`), read as `appEnv.PHOTOS_API`.
- **gallery-apps / memo-apps / module/purchasing**: base URLs removed from
`.env.dev` / `.env.example`; `NODE_ENV="development"` added.

## Minimize Deps · 2026-07-26

Drop the direct `devextreme` dependencies — they now come transitively through
`@mono-lit/utility` — and **pin** the remaining shared versions exactly (remove the `^`
caret) so pnpm dedupes to the single copy `@mono-lit/utility` / `@mono-lit/helper` bundle.
The shared helpers, notification component and types are imported from
`@mono-lit/utility/runtime` under their `Mono*` names. Update your own imports the
same way.

The helper surface is **`useMonoUtility()`**. `useUtils` is still exported from
`@mono-lit/utility/runtime`, but `useMonoUtility` is the public name.

### mono-nuxt-host

`github.com/your-org/mono-nuxt-host` · branch `main` · `4b6a0ec`

```diff
# package.json
- "devextreme": "catalog:frontend",
- "devextreme-vue": "catalog:frontend",
```

```diff
# pnpm-workspace.yaml (catalogs)
nuxt:
- nuxt: ^4.5.0
+ nuxt: 4.5.0
- "@nuxt/kit": ^4.5.0
+ "@nuxt/kit": 4.5.0
frontend:
- devextreme: 25.1.6
- devextreme-vue: 25.1.6
- yup: ^1.7.1
+ yup: 1.7.1
+ lit:
+ "nuxt-ssr-lit": "1.6.33"
+ "@lit-labs/ssr": "3.2.2"
```

```ts
import {useMonoUtility} from '@mono-lit/utility/runtime'

import { MonoNotifAction } from '@mono-lit/utility/runtime'

import type { MonoValidateError as ValidateError } from '@mono-lit/utility/runtime'

import { type MonoOdataMapTypes } from '@mono-lit/utility/runtime'

export {MonoSchemaObject as SchemaObject} from '@mono-lit/utility/runtime'
```

```vue

```

### mono-vue-host

`github.com/your-org/mono-vue-host` · branch `main` · `049e72d`

```diff
# package.json
- "devextreme": "catalog:frontend",
- "devextreme-vue": "catalog:frontend",
```

```diff
# pnpm-workspace.yaml (catalogs → frontend)
- devextreme: 25.1.6
- devextreme-vue: 25.1.6
- yup: ^1.7.1
+ yup: 1.7.1
```

```ts
import {useMonoUtility} from '@mono-lit/utility/runtime'

import { MonoNotifAction } from '@mono-lit/utility/runtime'

import { MonoValidateError as ValidateError } from '@mono-lit/utility/runtime'

import { type MonoOdataMapTypes } from '@mono-lit/utility/runtime'

export {MonoSchemaObject as SchemaObject} from '@mono-lit/utility/runtime'
```

```vue

```

### mono-vue-remote

`github.com/your-org/mono-vue-remote` · `example-vue-host` `21dd12d` ·
`example-nuxt-host` `66e192a`

```diff
# package.json
- "devextreme": "catalog:frontend",
- "devextreme-vue": "catalog:frontend",
```

```diff
# pnpm-workspace.yaml (catalogs → frontend)
- devextreme: 25.1.6
- devextreme-vue: 25.1.6
- yup: ^1.7.1
+ yup: 1.7.1
```

```ts
import { useMonoUtility } from '@mono-lit/utility/runtime'

import type { MonoOdataMapTypes } from '@mono-lit/utility/runtime'

import {
MonoSchemaObject as SchemaObject,
MonoValidateError as ValidateErrorComplex,
MonoValidateErrorSingle as ValidateErrorSingle,
} from '@mono-lit/utility/runtime'

export type DTO_BrandTypes = MonoOdataMapTypes
```

---
URL: "https://mono-libs.netlify.app/repo/useful-utils"
LLMS_URL: "https://mono-libs.netlify.app/repo/useful-utils.md"
---

# Useful Utils

Every public API `@mono-lit/utility` ships, grouped by entry point. Type-only exports are left out —
import them from the same entry as the value they belong to.

**Reach for these before writing custom code** (Rule 13 in [Template Rules](../ai/template)).

## `@mono-lit/utility/runtime`

App runtime: config, state, cookies, JWT, and the helper bundles.

| API | What it is |
| --- | --- |
| `createMono(config)` | Vue plugin — `app.use(createMono(monoConfig))`. |
| `initMono(config)` | The federation init `createMono` wraps. |
| `monoConfig()` | The resolved `mono.config.ts` at runtime. |
| `monoEnv()` | Resolved `env` block. |
| `monoState()` | Reactive mono state — `cookie`, `jwt`, `env`, `menu`. |
| `monoStatePatch()` / `monoStateReset()` | Patch / reset that state. |
| `monoUseState()` / `useState()` | Nuxt-style shared state, usable in a Vue app. |
| `nuxtStateKeys()` / `clearNuxtState()` | Inspect / clear those state keys. |
| `monoProvide()` / `monoInject()` | Cross-app provide/inject — see [Provide & Inject](./provide-inject). |
| `monoCookie()` / `useMyCookie()` | Cookie read/write. |
| `monoJwt()` / `useMyJwt()` | Decode a JWT cookie (`cookieDecode`). |
| `monoToken()` / `useMyToken()` | Raw token access. |
| `monoStorage()` / `useMyStorage()` | Local/session storage. |
| `useMyFetch()` | Re-export of the fetching helper. |
| `setMonoEventResolver(fn)` | Server-side cookie source for Nuxt — set in `app/plugins/mono.ts`. |
| `defineLayout(...)` | Declare a layout for the federated layout resolver. |
| `MonoNotivue` | Notification renderer component. |
| `MonoNotifAction` | The action-notification card `notif` renders. |
| `useMonoUtility()` / `useMonoUtils()` | The helper bundle below (`useMonoUtils` is an alias). |
| `useUtils()` | Same bundle as `useMonoUtility()` (older name). |

### `useMonoUtility()` helpers

| Helper | Signature | What it does |
| --- | --- | --- |
| `notif` | `notif(options): Promise` | Success / info / warning / error / promise toast, optional routing + redirect. |
| `validateAllSchema` | `({ schema, input, error }, cb?): Promise` | Validate a whole form object against a Yup schema. |
| `validateSchema` | `({ schema, field, input, error }, cb?): Promise` | Validate a single field. |
| `validateAllSchemaCheck` | `(error): boolean` | `true` if any field is currently invalid. |
| `clearSchemaValidation` | `({ error })` | Recursively reset all errors. |
| `replacerData` | `({ fn, type, item, key, items })` | Add / update / remove a row in an array or a DevExtreme DataSource. |
| `filterOrIn` | `(field, values, combine?)` | Build an OData `in` / chained `or` filter. |
| `dxFilterToString` | `({ filter, encode? })` | DevExtreme filter object → OData v4 `$filter` string. |
| `isDate` | `(value): value is Date` | Valid `Date` or parseable date string/number. |
| `isJSONString` | `({ input, strict?, root? })` | Is this string valid JSON. |
| `safeJSONParse` | `(str): any` | Parse JSON with fallbacks; `null` on failure. |

`filterOrIn(field, values, combine?)` has two output shapes, and they are not
interchangeable:

```ts
filterOrIn('OrderID', [1, 2]) // [['OrderID','=',1], 'or', ['OrderID','=',2]]
filterOrIn('OrderID', [1, 2], true) // ['OrderID', 'in', [1, 2]]
```

The default `or` chain is what a **DevExtreme store** understands — pass it to
`store().load({ filter })` or a DataSource.

The `combine: true` form is for the **string** path only: `dxFilterToString`
renders it as `OrderID in (1,2)`, for a URL you build yourself. It does not
survive a round trip back into a store, in either direction:

| what you pass to `store().load({ filter })` | what is sent | result |
| --- | --- | --- |
| `['OrderID','in',[1,2]]` | *nothing* | throws `E4003 — Unknown filter operation is used: in` |
| `['OrderID in (1,2)']` | `OrderID in (1,2) eq true` | 400 |
| `'OrderID in (1,2)'` | `OrderID in (1,2) eq true` | 400 |
| `[['OrderID in (1,2)']]` | `(OrderID in (1,2) eq true)` | 400 |
| `filterOrIn('OrderID',[1,2])` | `(OrderID eq 1) or (OrderID eq 2)` | **200** |

A lone string is read by DevExtreme as a boolean-field shorthand, so it always
gets ` eq true` appended — there is no raw-`$filter` passthrough through
`filter`. To send a literal `$filter`, set it in the store's `beforeSend` and
leave `filter` out of the load options.

Note also that `in` is OData **4.01**. A 4.0 service rejects it outright — the
public Northwind endpoint answers
`Microsoft.OData.Core.ODataException: Syntax error at position 10` — while
TripPin accepts it.

Yup is an optional peer — see the [Yup](../addons/yup) and [Notivue](../addons/notivue) addons.

## `@mono-lit/utility/fetching`

See [Data Fetching](./data-fetching) and [DataSource](../odata/datasource).

| API | What it is |
| --- | --- |
| `monoFetch` | REST fetch with auth, refresh and error handling. |
| `monoFetchOdata` | OData fetch. |
| `monoFetchOdataUnique` | OData fetch for a single entity. |
| `monoCreateFetcher` | Build a reusable fetcher. |
| `monoStaticDataSource` | DataSource over a static array. |
| `monoTryCatchDatasource` | Wrap a DataSource with error handling. |
| `monoLoadChuckStores` | Chunked store loading. |
| `monoConfigureFetching` / `monoResetFetchingConfig` | Set / clear runtime fetching options (e.g. `unauthCall`). |
| `monoFetchingRuntime` | The current resolved fetching runtime. |
| `monoRestBaseUrl` / `monoOdataBaseUrl` / `monoOdataSource` | Resolved API bases and OData service. |
| `monoRequestToken` | Token sent on requests. |
| `monoMockDb` / `resetMonoMockDb` | Mock IndexedDB backend — see [Mock API](./mock-api). |
| `promiseWrapper` | Await a promise into an error/data pair. |

## `@mono-lit/utility/vite`

Everything a Vue Host or Remote wires in `vite.config.ts` — see [Setup](./setup).

| API | What it is |
| --- | --- |
| `monoRepo(options?)` | **The entry point.** `await monoRepo({ command })` → `mono.pages` / `layouts` / `components` / `autoImport` / `vite()` / `ecosystem()`. |
| `monoVite(ctx, opts?)` | The mono plugin set — register **last**. |
| `monoVue(options?)` | Compat plugins for a Vue app against a Nuxt Host — the hybrid pairing, possible but risky (alias: `monoNuxtHost`); register before `VueRouter()`. |
| `monoPages` / `monoPagesOptions` | vue-router routesFolder + `extendRoute`, own and federated. |
| `monoLayouts` / `monoLayoutsOptions` | `layoutsDirs`, driven by `template`. |
| `monoComponents` / `monoComponentsOptions` | unplugin-vue-components dirs. |
| `monoAutoImport` / `monoAutoImportOptions` | unplugin-auto-import dirs + imports. |
| `monoExtendRoute(options?)` | The `extendRoute` that stamps `meta.layout`. |
| `reconcileEcoPlugins(plugins)` | Stand down a duplicate ecosystem plugin. |
| `sanitizeForExpose(value)` | The sanitiser behind `__MONO_CONFIG_EXPOSE__`. |
| `ecoKeyForSub(sub)` / `MONO_ECO_SUB_KEYS` / `MONO_ECO_PLUGIN_NAMES` | Ecosystem key lookup tables. |
| `createRootLoader(rootDir)` / `canResolveFromRoot(rootDir, id)` | Resolve a module from an app root. |
| `parsePageMeta` / `parsePageMetaFromFile` | Read `definePageMeta` / `definePage` blocks. |

**Nuxt-compat transforms** (added automatically when a federated app is `type: 'nuxt'`):
`monoStripPageMeta`, `monoPageMetaToDefinePage`, `monoLayoutSlotToRouterView`, `monoNuxtState`,
`monoNuxtStateToRef`, `monoNuxtLink`, `monoNuxtLinkToRouterLink`, `monoRouterLink`,
`monoRouterLinkToNuxtLink`.

## `@mono-lit/utility/nuxt` · `@mono-lit/utility/nuxt-runtime`

| API | What it is |
| --- | --- |
| `@mono-lit/utility/nuxt` (default) | The Nuxt module — aliases, `server.fs.allow`, the config define, ecosystem merge. Add to `modules[]`. |
| `setMonoEventResolver(fn)` | Server-side request resolver. |
| `monoCookieDriver` / `monoCookieStorage` | h3-backed cookie driver for SSR. |

## `@mono-lit/utility/config`

Loaded by `mono.config.ts` itself — see [Config](./config).

| API | What it is |
| --- | --- |
| `defineConfig(config)` | Define `mono.config.ts`. |
| `resolveMonoConfig(config)` | Resolve the `extends` chain into one config. |
| `resolveExtendsAppNames` / `resolveExtendsEcosystems` | Which layers and directories are switched on. |
| `resolveEnv(...)` | Resolve the `env` block. |
| `srcDirForType(type)` / `MONO_SRC_DIR` | `'vue'` → `src/`, `'nuxt'` → `app/`. |
| `dedupeBy` / `dedupeConfigArrays` | Merge helpers for the name-keyed arrays. |

Types: `MonoConfig`, `MonoAppConfig`, `MonoAppType`, `MonoTemplate`, `MonoEnvConfig`,
`MonoFetchingConfig`, `MonoJwtConfig`, `MonoApiEntry`, `MonoAuthConfig`, `MonoMockDbConfig`,
`MonoSyncTransport`, `JWTCompleteTokenTypes`, `SidebarMenu`, `Permission`.

## `@mono-lit/utility/config/node`

Node-only — what the CLI and the build integrations use.

| API | What it is |
| --- | --- |
| `loadMonoConfig` / `getMonoConfig` | Load `mono.config.ts` outside the browser (c12/jiti). |
| `monoAlias(options?)` | Build the `@mono-*` alias map. |
| `monoTsconfigPaths` / `buildMonoTsconfig` / `runMonoPrepare` | What `mono prepare` runs. |
| `monoMissingApps` / `formatMissingApps` / `monoStubAliases` | Report and stub apps not yet synced. |
| `extractConfig` / `extractConfigName` / `stripCommentsSafe` | Static parse of the config text (how `type` is read before eval). |
| `MONO_DIR` / `MONO_APPS_DIR` / `MONO_TSCONFIG_REF` | `.mono/` path constants. |

Skills / session storage (`mono skills`): `isSkillsEnabled`, `readToken`, `loadSkillsEnv`,
`detectActor`, `ghRepoMeta`, `ghBranchExists`, `ghGetContent`, `ghPutFile`, `ghTree`,
`GithubHttpError`, `normalizeAppId`, `resolveAppId`, `isGenericAppName`, `stagingRoot`,
`loadStagedSession`, `listSessions`, `validateStagedSession`, `moveToFailed`, `removeSession`,
`cacheDir`, `chunkConversation`, `redact`, `redactBuffer`, `buildSavePlan`, `runSave`,
`runRead`, `runSearch`, `runCheck`, `runSessionShow`.

## `@mono-lit/utility/mock-db`

The browser mock backend — see [Mock API](./mock-api).

| API | What it is |
| --- | --- |
| `createMockDb` / `openMockDb` / `monoMockDb` / `resetMonoMockDb` | Create, open, access, reset the database. |
| `createMockStore` | A store over one entity. |
| `parseMockSchema` | Parse the `mockIndexedDB` schema. |
| `generateSeed` / `createRandom` / `orderEntitiesByDependency` | Seed generation. |
| `executeQuery` / `matchMockRoute` / `toODataEnvelope` | Serve an OData request. |
| `parseQuery` / `parseFilter` / `parseExpand` / `parseApply` / `parseField` / `parseKeySegment` / `tokenize` / `normalizeSegment` | OData query parsing. |
| `evaluateFilter` / `applyTransforms` | Apply `$filter` / `$apply` in memory. |
| `isIndexedDbAvailable` | Environment check. |

## `@mono-lit/utility` (root)

| API | What it is |
| --- | --- |
| `monoEcosystem(options)` | Resolve ecosystem directories by hand. |
| `mergeEcosystem(...)` | Merge two ecosystem sets. |
| `htmlPath` / `htmlToVue` | Resolve an HTML file and turn it into a Vue component. |

---
URL: "https://mono-libs.netlify.app/ui/accordion"
LLMS_URL: "https://mono-libs.netlify.app/ui/accordion.md"
---

# Accordion

A single expand/collapse unit with header (icon + title + optional subtitle + optional trailing actions) and a body. Compose multiple together for a typical FAQ or settings group. Toggle **Vue / CSS** to switch the live demo and source together.

The look is Basecoat's `.accordion` (see [Theme](./theme)): a `p-4` row with a `text-sm font-medium` title and a `size-4` chevron that rotates when the item opens, over a `text-sm` body. **In a group** the items flatten into one flush list with a hairline between them, exactly as upstream renders `.accordion > details`; **on its own** an item keeps this component's frame (border, radius, `shadow-xs`), which upstream has no equivalent for. Dark mode is built in.

## Basic

Single accordion with a title and body.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Title & subtitle

The header text comes from three places. When more than one is given, the most specific wins:

1. **`slot="header"`** replaces the whole left side of the row: the icon, the title and the subtitle. The `actions` slot and the chevron stay, and the row is still the toggle.
2. **`slot="title"` / `slot="subtitle"`** each replace one line.
3. **`title` / `subtitle` props** are plain text.

The old prop names `label` / `description` are still accepted (as properties and as attributes) as aliases of `title` / `subtitle`. Likewise the old slot names `slot="label"` / `slot="description"` still work as aliases of `slot="title"` / `slot="subtitle"`; when both an old and a new name are given, the new one wins. The secondary line renders `[mono-subtitle]` (and, for existing CSS, its old name `[mono-description]` too).

See the [Slots](#slots) demo for `slot="header"` in action.

## Sizes

Small, medium and large.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Colors

Pick a colour and both accordions take it — the accent on the active border, icon background and arrow re-paints live.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## States

Default-open, default-closed and disabled.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Icon & subtitle

Leading icon plus a subtitle under the title.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Group

Multiple stacked items in the group helper — one flush list with a hairline between the items, which is Basecoat's `.accordion`. Four of the eight flavors (maia, mira, luma, rhea) also frame the group itself; on vega it is a bare column.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Slots

Custom title, subtitle, icon, actions and body via named slots. The second item uses `slot="header"` to replace the title and subtitle with its own markup — the icon, actions and chevron are kept.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Event log

Live log of `toggle`, `open` and `close` events.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Customized

Override per-element styling with `cssClass` (Vue) or utility classes (CSS).

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## CSS Variables

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

Every accordion is themed through `--mono-accordion-*` custom properties. Setting one on the element, on any wrapper/ancestor, or inline all work — custom properties inherit, and they **pierce the shadow-DOM boundary**, so the same overrides apply to `` and the shadow build. The `size` and `color` props set presets, but an explicit `--mono-accordion-*` override always wins. To re-skin globally, set the underlying [tokens](./theme) (`--card`, `--border`, `--muted-foreground` …) or switch flavor.

| Variable | Default | Controls |
| --- | --- | --- |
| `--mono-accordion-accent` / `-` | `--primary` / the ten roles | The colour the chevron, the focus ring and the open edge take (set by `color`) |
| `--mono-accordion-bg` (alias `-surface`) / `-text` / `-border` | `--card` / `--card-foreground` / `--border` | The item's fill, ink and edge |
| `--mono-accordion-shadow` | `--mono-shadow-xs` | The standalone item's elevation (a grouped item has none) |
| `--mono-accordion-open-bg` (alias `-head-bg`) / `-open-border-color` / `-open-shadow` | the item's own surface / the role at 32% over `--border` / a soft role glow | The open item. Four flavors set `-open-bg` to `bg-muted/50`; vega leaves it alone |
| `--mono-accordion-radius` / `-radius-` | `--mono-radius-md` at md | Corner radius |
| `--mono-accordion-pad-x-` / `-pad-y-` | 4 × `--mono-spacing` at md (`p-4`) | Head and body padding |
| `--mono-accordion-gap` | 3 × `--mono-spacing` | Gap between the head's parts |
| `--mono-accordion-title-font-` / `-title-weight` / `-title-hover-decoration` | `--mono-text-sm` / medium / `underline` | The title. Upstream underlines it on hover — set `none` to drop that |
| `--mono-accordion-head-hover-tint` / `-head-hover-bg` | `0%` / built from it | A hover fill for the row, off by default (the underline is the cue). A flavor sets the ALPHA; a consumer can set the colour outright |
| `--mono-accordion-description-font` / `-description-color` | `--mono-text-xs` / `--muted-foreground` | The second line (the subtitle) |
| `--mono-accordion-body-font-` / `-body-line-height` / `-body-color` | `--mono-text-sm` / its line-height / inherit | The body |
| `--mono-accordion-arrow-size` / `-arrow-color` / `-arrow-open-color` | `size-4` / `--muted-foreground` / the role | The chevron |
| `--mono-accordion-glyph-size` / `-glyph-radius` / `-glyph-bg` / `-glyph-color` | 7 × `--mono-spacing` / `--mono-radius-sm` / the role at 14% / the role | The leading icon chip |
| `--mono-accordion-ring-color` / `-ring-width` | the role / `--mono-ring-width` | The head's focus ring |
| `--mono-accordion-group-gap` / `-group-radius` / `-group-border-width` / `-group-border-color` | `0` / `0` / `0` / `--border` | The group. maia, mira, luma and rhea frame it (`overflow-hidden rounded-2xl border`); a gap turns the list back into separate boxes, and the dividers go with it |
| `--mono-accordion-duration` | `--mono-duration` | Open/close animation duration (body collapse + chevron); set `0s` for an instant toggle |

## Performance

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

An accordion body is always rendered — collapsing it is a visual state, not an unmount —
so the consumer's content is never destroyed and never has to be rebuilt on reopen. When a
body holds many components, that has two separate costs, and they have different fixes.

**Putting a long list of accordions on screen.** A collapsed body is skipped for layout and
paint entirely (`content-visibility: hidden`), so closed panels cost almost nothing no
matter what is inside them. Measured with ~320-node bodies, initial layout for 40 panels
drops from **157 ms to 18 ms**, and stops growing with the panel count. This is automatic.

**Toggling one panel open or closed.** This cost is dominated by the expand animation:
`grid-template-rows` is a layout property, so the browser re-measures the body's whole
subtree on every frame. For one open+close cycle with those same bodies, **24.8 ms animated
vs 3.6 ms** with the animation off. So if your bodies are heavy, turn it off:

```css
mono-accordion.heavy { --mono-accordion-duration: 0s; }
```

That is the single most effective change for a sluggish toggle — roughly 85% of the cost is
the animation, not the content.

Two consequences of a collapsed body being skipped, both intentional:

- Its contents are out of the tab order and the accessibility tree, so Tab
no longer lands on invisible form fields inside a closed panel.
- Its contents are not matched by the browser's in-page find (Ctrl+F).

Browsers without
[`transition-behavior: allow-discrete`](https://developer.mozilla.org/docs/Web/CSS/transition-behavior)
keep collapsed bodies in layout — the accordion behaves identically, just without the
saving.

## Types

```ts
import { AccordionProps } from '@mono-lit/helper'
```

| Prop | Value | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Title text shown in the accordion header. `slot="title"` replaces it, and `slot="header"` replaces the icon, title and subtitle together. |
| `subtitle` | `string` | — | Secondary text shown under the title. `slot="subtitle"` replaces it. |
| `label` | `string` | — | — |
| `description` | `string` | — | — |
| `modelValue` | `boolean` | — | Bound open state; true when the accordion is expanded. |
| `disabled` | `boolean` | — | Disables interaction and dims the accordion. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xxl'` | — | Visual size of the accordion. |
| `color` | `'primary' \| 'secondary' \| 'success' \| 'danger' \| 'warning' \| 'info' \| 'teal' \| 'purple' \| 'neutral' \| 'dark'` | — | Color theme of the accordion. |
| `cssClass` | `AccordionCssClass` | — | Per-element class overrides. |

---
URL: "https://mono-libs.netlify.app/ui/alert"
LLMS_URL: "https://mono-libs.netlify.app/ui/alert.md"
---

# Alert

A callout for a short message: an optional icon, a title and a subtitle, with no header region. Alerts are meant to stack, and the optional ✕ hides one. Toggle **Vue / CSS** to switch the live demo and source together.

The look is Basecoat's `.alert` (see [Theme](./theme)): a card surface edged with `--border`, `rounded-lg`, `px-4 py-3` and `text-sm`, with the icon in its own column. Every theme style has its own alert (lyra and mira are compact, luma and rhea are `rounded-2xl`, sera adds a coloured bar on the start edge), and dark mode comes from the colour tokens.

```vue

```

## Basic

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Variants

The same four looks as the [button](./button): `outline` (the default, Basecoat's alert), `tonal`, `solid` and `text`.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Colors

`neutral` (the default) is the plain alert. `danger` is Basecoat's destructive alert, and the same recipe is applied to every other colour.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Sizes

`xs` to `xxl`. Every size is the `md` metrics (padding, type, icon, gaps) times one factor, so a theme only tunes `md` and the whole scale follows.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Icon

`icon` takes an iconify class (`i-mdi-information-outline`) or plain text (an emoji, a letter). `slot="icon"` takes any markup.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Slots

When more than one is given, the most specific wins:

1. **`slot="body"`** replaces the icon, title and subtitle: the whole content. **Plain children (no `slot` attribute) are the body too.** The ✕ stays.
2. **`slot="title"` / `slot="subtitle"` / `slot="icon"`** each replace one part.
3. **`title` / `subtitle` / `icon` props** are plain text.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Clearable & stacking

`clearable` (or `closeable`) adds a ✕. Clicking it hides the alert by setting the element's own `hidden` attribute; no event is involved. `@click` on an alert is just the browser's click, and the ✕ does not trigger it. To show a hidden alert again, remove the `hidden` attribute or re-render it.

Stacked alerts keep a gap between them automatically, and a hidden one takes no room, so the rest move up. Wrap them in `[mono-alert-group]` to lay them out as a column with their own gap.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## Nested

Alerts nest. An inner alert is plain content of the outer one, so it is the outer alert's **body**, and the body replaces the outer icon, title and subtitle. To keep a heading on the outer alert, put it in the body next to the inner alerts, as in the demo.

- **Own props:** every inner alert keeps its own colour, size and variant. Nothing is inherited from the outer alert.
- **✕:** each inner ✕ hides only its own alert.
- **Spacing:** consecutive inner alerts get the stacking gap.

Vue demo source:

```vue

```

CSS/native demo source:

```vue

```

## CSS Variables

| Variable | Default | Controls |
| --- | --- | --- |
| `--mono-alert-bg` / `--mono-alert-text` / `--mono-alert-subtext` | `--card` / `--card-foreground` / `--muted-foreground` | Surface, title ink, subtitle ink (neutral outline) |
| `--mono-alert-border-color` / `--mono-alert-border-width` | `--border` / `--mono-border-width` | Edge |
| `--mono-alert-radius` | `--mono-radius-lg` | Corner |
| `--mono-alert-padding-x` / `--mono-alert-padding-y` | 4 × / 3 × `--mono-spacing` | Padding at `md` (other sizes scale it) |
| `--mono-alert-gap` / `--mono-alert-icon-gap` | 0.5 × / 2.5 × `--mono-spacing` | Title↔subtitle gap / icon column gap |
| `--mono-alert-font-size` / `--mono-alert-line-height` | `--mono-text-sm` | Title type |
| `--mono-alert-subtitle-font-size` / `--mono-alert-subtitle-line-height` | `--mono-text-sm` | Subtitle type |
| `--mono-alert-title-weight` | `--mono-font-weight-medium` | Title weight |
| `--mono-alert-icon-size` / `--mono-alert-icon-offset` | 4 × / 0.5 × `--mono-spacing` | Icon box and its nudge onto the first line |
| `--mono-alert-clear-size` | 6 × `--mono-spacing` | The ✕ button |
| `--mono-alert-accent-bar-width` | `0px` (sera: `2px`) | The start-edge bar in the alert's colour |
| `--mono-alert-stack-gap` / `--mono-alert-group-gap` | 3 × `--mono-spacing` | Space between stacked alerts |

## Types

```ts
import { AlertProps } from '@mono-lit/helper'
```

| Prop | Value | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | The headline. `slot="title"` replaces it. |
| `subtitle` | `string` | — | The line under the title. `slot="subtitle"` replaces it. |
| `icon` | `string` | — | The leading icon: an iconify class (`i-mdi-information-outline`) or plain text (an emoji, a letter). `slot="icon"` replaces it. |
| `color` | `'primary' \| 'secondary' \| 'success' \| 'danger' \| 'warning' \| 'info' \| 'teal' \| 'purple' \| 'neutral' \| 'dark'` | — | Colour role. `neutral` (default) is Basecoat's plain alert. |
| `variant` | `'outline' \| 'solid' \| 'tonal' \| 'text'` | — | `outline` (default, Basecoat's look), `tonal`, `solid` or `text`. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xxl'` | — | Scale step, `xs` → `xxl`. Default `md`. |
| `clearable` | `boolean` | — | Show a ✕ that hides the alert (it sets the element's own `hidden` attribute). The ✕ stays when `slot="body"` replaces the rest. |
| `closeable` | `boolean` | — | Same as `clearable`. |
| `clearLabel` | `string` | — | Accessible name of the ✕. Default `'Close'`. |
| `cssClass` | `AlertCssClass` | — | Extra classes per part. |

---
URL: "https://mono-libs.netlify.app/ui/breadcrumb"
LLMS_URL: "https://mono-libs.netlify.app/ui/breadcrumb.md"
---

# Breadcrumb

A wayfinding component for page hierarchies — pair it with a page header above the title and subtitle. Items render as `` when they include `href`, as `}}

Card Title

Card Title

Outer card

Nested card

Conditional nested card

Outer card

Nested card

Conditional nested card

Elevated

Outlined

Flat

Tonal

Glass

Elevated

Outlined

Flat

Tonal

Glass

Bordered

Hoverable

Clickable

Disabled

Bordered

Hoverable

Clickable

Disabled

Action Card

Interactive Card

Action Card

Interactive Card

Click me

Click me

Toggle me

Toggle me

Click or press Enter

Click or press Enter

Revenue Growth

Revenue Growth

{{ label }}

Extra small

Small

Medium (default)

Large

Extra large

Extra extra large

Pro plan

Pro plan

Default CSS Icon

Custom SVG Icon

Default CSS Icon

Custom SVG Icon

Profil

form.items() — live

submitted

Watchers

form.items()

watcher log

Laporan

form.items()

events

Main content

Main content

{{ titles[active] || 'Dashboard' }}

{{ activeTitle() }}

{{ items.find((i) => i.id === active)?.title || 'Dashboard' }}

{{ activeTitle() }}