KaUI is a source registry for shadcn-style applications. Instead of publishing a black-box component package, it ships editable source files through registry endpoints that the shadcn CLI can install directly into an app.
Problem
In product code, UI primitives are rarely useful as sealed packages. Teams need to inspect them, adapt them, move them across design systems and own the code after installation. A package dependency is convenient until the first product requirement cuts across its abstraction.
The goal was to build a registry that behaves like a library during install but behaves like local source after install.
Architecture
The site is built with Astro and Starlight for documentation, React for live examples and a generated public registry under /r/*.json. The registry source lives in src/registry, while the docs live in src/content/docs. A build step reads registry.json, loads each source file, transforms internal imports and writes shadcn-compatible JSON files to public/r.
That build step is important. Component source can use clean internal paths during development, but the installed output needs to point at the consumer's app structure: @/components/ui/*, @/hooks/* and registry dependency URLs. The generator is the boundary between authoring ergonomics and installation ergonomics.
Key decisions
The first decision was to make source the distribution unit. Each registry item declares its files, targets, npm dependencies and registry dependencies. The generated item includes the actual file content, so the consuming app receives code it can edit.
The second decision was to keep the registry catalog separate from registry items. /r/registry.json is the discovery endpoint for listing and search. The individual /r/{name}.json endpoints carry file contents. That keeps discovery small and makes each install request explicit.
The third decision was to document components as behavior, not screenshots. AsyncScope, for example, is explained as a coordination layer between an async state machine and UI consumers. The docs show why it is not a replacement for TanStack Query or SWR; it broadcasts action state inside a subtree while the data library still owns caching and deduplication.
Hard parts
The main challenge was dependency shape. Registry items can depend on npm packages, local UI primitives and other registry items. A component like async-button depends on button, utils and use-async; a component like combobox depends on popover, command, skeleton and controlled-state helpers. The generator has to preserve that graph so installation pulls the complete working surface, not just the top-level file.
Another challenge was import rewriting. Source files are authored in the registry repo, but installed files live in a user's application. Relative and registry-internal imports need to become the aliases shadcn apps expect. This is why the generator rewrites paths before writing JSON.
The documentation system had its own tradeoff. Astro/Starlight is excellent for fast static docs, but interactive React demos still need islands. I kept demos small and colocated examples under the registry source so docs stay honest: each example is real component code, not a mocked screenshot.
What this demonstrates
KaUI shows library and developer-experience thinking: source distribution, dependency graphs, generated artifacts, docs architecture and API boundaries. It is a small project, but it exercises the kind of taste that matters when building tools other developers have to live with.