# Registry — Build your own Source: https://lumeo.nativ.sh/docs/registry # Registry A registry is a static JSON file that catalogues components so `lumeo-cli` and the MCP server can install them, search them, and help LLMs author code against them. Lumeo ships one out of the box, but anyone can publish their own so `lumeo add` and Claude / Cursor work against a third-party library. ## Our built-in registry Lumeo maintains a reference registry for the components in this site. It's the same file `lumeo add` hits by default, and the same file our MCP server indexes at build time. - Raw JSON: [/registry.json](/registry.json) - Source on GitHub: [src/Lumeo/registry/registry.json](https://github.com/Brain2k-0005/Lumeo/blob/master/src/Lumeo/registry/registry.json) The registry is produced by `tools/Lumeo.RegistryGen/` — a small .NET CLI that walks `src/Lumeo/UI/` and emits a JSON file. If you want to auto-produce your own registry instead of hand-authoring one, it's a reasonable reference implementation to fork. ## Schema reference The file has two top-level fields and an open-ended map of component entries. { "$schema": "https://lumeo.nativ.sh/registry-schema.json", "version": "2.0.0", "components": { "": { ... } } } ### Top-level fields Field Type Required Description $schema string (URL) recommended Pointer to the JSON schema for editor tooling. version string (SemVer) yes Registry version. Bump on breaking field changes so consumers can guard. components object yes Map of component slug → entry. The slug is what `lumeo add ` uses. ### Per-component entry Each value in `components` is a JSON object that looks like this: { "name": "Button", "category": "Forms", "description": "Versatile button with variants, sizes, icons, loading states.", "files": \["UI/Button/Button.razor"\], "dependencies": \["icon"\], "cssVars": \["--color-primary", "--color-primary-foreground"\], "registryUrl": "https://example.com/registry/button.json" } Field Type Required Description name string yes PascalCase component name (used in docs and code examples). category string yes Grouping for `lumeo list` and the MCP catalog (Forms, Layout, Feedback, etc.). Pick from a short controlled set or invent your own. description string yes One-line blurb shown by `lumeo list` and in MCP search results. Keep it under 120 chars. files string\[\] yes Relative paths to every file needed for this component. `lumeo add` fetches each one. dependencies string\[\] no Slugs of other components this one needs. `lumeo add` resolves them recursively. cssVars string\[\] no Lumeo theme tokens the component reads. Helps `lumeo doctor` check the consumer's theme. registryUrl string (URL) no Per-component pointer useful when you split entries across multiple JSON files. requiresRuntime bool no New: set `true` if this component depends on Lumeo's runtime (services, interop, source generators). `lumeo-cli` will warn when installing without the `Lumeo` NuGet. Defaults to false. Tip Keep `description` under 120 chars — LLMs and `lumeo list` truncate longer blurbs. ## How `lumeo-cli` consumes it The CLI treats your registry URL as the single source of truth. The install flow: - `lumeo init` saves `registry: ""` in `lumeo.json`. - `lumeo add ` fetches `registry.json`, finds the slug's entry, downloads each `files[]` entry (base URL derived from the registry URL — see next bullet), recursively installs `dependencies[]`, and rewrites `@namespace Lumeo` to the consumer's namespace. - File URLs: by convention, `lumeo-cli` takes the registry URL, strips the filename, and joins each relative `files[]` path against that base. https://example.com/lumeo/registry.json + UI/Button/Button.razor → https://example.com/lumeo/UI/Button/Button.razor Self-hosters Serve your raw `.razor` files from the same origin as the registry JSON. Relative paths won't work across origins. ## How the MCP server consumes it - `tools/lumeo-mcp/` reads the registry at build time (via its `prebuild` script) and exposes every entry through `lumeo_list_components` / `lumeo_get_component` / `lumeo_search` plus the `lumeo://component/{name}` resource. - For third-party registries you want exposed to LLMs, fork `tools/lumeo-mcp/`, update the `sync-registry.mjs` URL, and publish your own npm package — the protocol stays the same. ## Build your own — 5-step quickstart The registry format is a contract, not a framework — any static host will do. ### 1\. Create your component library Author a normal Blazor class library that targets `net10.0` with the Razor SDK. Each component is a regular `.razor` file — no special conventions required. ### 2\. Author `registry.json` Hand-write it for small libraries, or generate it. For a reference generator, see [tools/Lumeo.RegistryGen/Program.cs](https://github.com/Brain2k-0005/Lumeo/blob/master/tools/Lumeo.RegistryGen/Program.cs) — it scans a components directory and emits a schema-compliant registry. ### 3\. Host the registry + raw files Any static host works: GitHub Pages, Cloudflare Pages, Netlify, a CDN, your own bucket. Make sure CORS allows fetches from arbitrary origins so `lumeo-cli` can hit it cross-origin if needed. ### 4\. Test with `lumeo-cli` Point a consumer project at your registry and run `lumeo add my-slug`. Verify files land with the right namespace and that dependencies resolve recursively. lumeo init --registry https://example.com/lumeo/registry.json lumeo add my-slug ### 5\. (Optional) Publish your own MCP server Fork `tools/lumeo-mcp/`, point its `sync-registry.mjs` at your hosted JSON, build, and publish to npm. Claude / Cursor users can then install your server and get completions, docs, and examples for your components. ## JSON Schema The registry at `/registry.json` is `$schema`\-compatible with `https://lumeo.nativ.sh/registry-schema.json`. Hosting that URL is planned; for now, the schema lives alongside the generator in `tools/Lumeo.RegistryGen/` in the repo, so you can copy it locally and validate with any standard JSON Schema tool. Looking for a list of Lumeo's own components? Use the sidebar or the [Components index](components) .