Contract 2.0.0 · Node.js >=20
ui8kit is a file-based registry CLI (shadcn-style): it fetches registry items from a CDN (or local server) and writes source files into your app. It does not treat node_modules as the kit source of truth, so Tailwind and bundlers see real classes and files.
This docs set covers concepts, configuration, every command, the registry JSON contract, CDN/cache behavior, publishing, end-to-end scenarios, troubleshooting, and migration from v1.
| Doc | Contents |
|---|---|
| Getting started | Install, first init / add, verification |
| Concepts | Mental model, folders, types, runtimes, path remap |
| Configuration | Full ui8kit.config.json reference |
| Commands | Every command, flag, and example |
| Registry format | Item / index JSON contract |
| CDN and cache | URL resolution, pinning, offline cache |
| Publishing a registry | scan → build → host /r |
| Troubleshooting | Common failures and fixes |
| Migration v1 → v2 | Breaking changes checklist |
| Scenario | Audience |
|---|---|
| Consumer app (React) | App teams installing primitives |
| Svelte / Solid / Vue | Multi-runtime digests |
| Go Templ / PHP | Kit on disk without a JS framework |
| Private / strict CDN | Locked registry URL + version pin |
| Maintain & publish registry | Authors assembling packages/registry/r |
| CI dry-run & upgrades | Automation, diff, force updates |
┌─────────────────────┐
│ Registry CDN `/r` │
│ index.json + items │
└──────────┬──────────┘
│ fetch
▼
┌──────────────┐ ui8kit add ┌────────────────────────┐
│ App project │ ◄──────────────── │ files under {dir}/… │
│ ui8kit.config│ │ components/ui, utils… │
└──────────────┘ └────────────────────────┘
Authors use the reverse path:
source kit → ui8kit scan → registry.json → ui8kit build → packages/registry/r
- Package README: ../README.md
- Maintainer scripts: ../scripts/README.md
- Changelog: ../CHANGELOG.md