ui8kit CLI v2

Universal shadcn-style registry service: init / add / list / diff / scan / build — fetch registry items and write files into your app (not into node_modules). Tailwind sees classes. Works for React, Svelte, Vue, Solid, Go Templ, Latte/Twig — via framework / runtime + path contracts.

Contract version: 2.0.0 · npm package: ui8kit@2.0.1 · digest: @ui8kit/registry@2.0.0

Full documentation (English):docs/README.md
Agents / maintainers:AGENTS.md · project hub: .project/README.md

Start here
Getting started	Install + first init/add
Commands	Complete CLI reference
Scenarios	React, Svelte, Templ, private CDN, publish, CI
Registry format	Item / index JSON contract

Idea

registry (CDN / digest) → npx ui8kit add → {dir}/components/ui/...
→ {dir}/utils, lib, blocks, layouts, …

Codegen (separate) emits primitives; this CLI installs registry packages into app folders and can scan/build local registry artifacts for publishing.

Requirements

• Node.js >=20 (or Bun)
• A project with package.json (created by init if missing)
• No hard requirement for Vite/React

New app — utils + UI (recommended)

Published digest: @ui8kit/registry@2.0.0 (/r on unpkg / jsDelivr).

Important (ui8kit@2.0.1):registry:utils is hidden from add / --all and is not pulled via registryDependencies yet. Install utils through init (do not pass --skip-core). A CLI fix is planned; until then follow this recipe.

1. Init (installs utils from CDN)

# Svelte example — omit --skip-core so core utils land under src/utils
bunx ui8kit@2.0.1 init --yes \
--framework svelte \
--runtime svelte \
--dir src \
--registry-url https://unpkg.com/@ui8kit/registry@2.0.0/r \
--strict-cdn

Confirm: src/utils/cn.ts (and friends) exist. If the folder is empty, re-run init without --skip-core or fetch utils manually (see below).

2. Fill ui8kit.config.json

After init, edit to pin CDN + runtime (example for Vite/Svelte under src/):

{
"contractVersion": "2.0.0",
"framework": "svelte",
"runtime": "svelte",
"typescript": true,
"globalCss": "src/app.css",
"dir": "src",
"aliases": {
"@": "./src",
"@/ui": "./src/components/ui",
"@/utils": "./src/utils"
},
"registry": "@ui8kit",
"registryUrl": "https://unpkg.com/@ui8kit/registry@2.0.0/r",
"registryVersion": "2.0.0",
"strictCdn": true,
"importStyle": "alias"
}

Path remap note: bricks import ../../utils. Keep utils at {dir}/utils. If you want MentorYChat-style src/kit, set "paths": { "ui": "kit" } in config for documentation — in 2.0.1 paths is ignored when registry files set target (they still install under components/ui). Workaround: after add, move src/components/ui/* → src/kit/ and leave src/utils in place. Do not set "utils": "kit/utils" without rewriting imports.

3. Add UI (runtime file filter)

bunx ui8kit@2.0.1 add button stack title text --runtime svelte --force
# or everything:
bunx ui8kit@2.0.1 add --all --runtime svelte --force

--runtime svelte keeps .svelte + *.shared.ts + *.variants.json only.

Also install npm peers used by utils if missing:

bun add clsx tailwind-merge
# or: npm install clsx tailwind-merge

Manual utils fallback (if init skipped core)

# Download item JSON and write files[] into {dir} by each file.target
curl -sL https://unpkg.com/@ui8kit/registry@2.0.0/r/utils/utils.json
# → write each files[].content to src/{files[].target}

Or with Node one-liner from app root (after init created src/):

node --input-type=module -e "import { mkdirSync, writeFileSync } from 'node:fs';import path from 'node:path';const item = await fetch('https://unpkg.com/@ui8kit/registry@2.0.0/r/utils/utils.json').then(r => r.json());for (const f of item.files) { const target = path.join('src', f.target); mkdirSync(path.dirname(target), { recursive: true }); writeFileSync(target, f.content); console.log('wrote', target);}"

Quick start (short)

bunx ui8kit@2.0.1 init --yes --framework svelte --runtime svelte --dir src \
--registry-url https://unpkg.com/@ui8kit/registry@2.0.0/r --strict-cdn
bunx ui8kit@2.0.1 add button --runtime svelte --force

Go / PHP (kit on disk). Prefer with core utils unless you only need markup:

bunx ui8kit@2.0.1 init --yes --framework templ --runtime templ --dir internal \
--registry-url https://unpkg.com/@ui8kit/registry@2.0.0/r --strict-cdn
bunx ui8kit@2.0.1 add button --runtime templ --force

Canonical folders under {dir}

Path	Role	Registry type
lib/	low-level runtime helpers	registry:lib
utils/	shared helpers (cn, …) — required by primitives	registry:utils
components/	composites	registry:component / composite
components/ui/	primitives (codegen digest)	registry:ui
blocks/	page sections	registry:block
layouts/	chrome / shells	registry:layout
variants/	variant maps	registry:variants
widgets/	UI + behavior	registry:widget

Safe remap intent (utils stay top-level under dir):

{
"dir": "src",
"paths": { "ui": "kit" }
}

Avoid "utils": "kit/utils" until the CLI rewrites relative imports (not in 2.0.1).

Config (ui8kit.config.json)

See the filled example in New app — utils + UI. Private CDN:

{
"contractVersion": "2.0.0",
"framework": "react",
"runtime": "react",
"dir": "src",
"globalCss": "src/app.css",
"registryUrl": "https://cdn.example.com/ui8kit/r",
"registryVersion": "2.0.0",
"strictCdn": true
}

CDN resolution order

1. --registry-url / registryUrl
2. cdnBaseUrls from config (replaces built-in defaults when set)
3. Built-in defaults (unpkg / jsdelivr for @ui8kit/registry@latest/r)

--strict-cdn + explicit URL → only that URL.

--registry-version rewrites @latest → @2.0.0 in URL templates when applicable.

Commands

init

bunx ui8kit init
bunx ui8kit init --yes --framework none --dir src
bunx ui8kit init --yes --framework templ --dir internal
bunx ui8kit init --registry-url https://unpkg.com/@ui8kit/registry@2.0.0/r --strict-cdn

Creates ui8kit.config.json + canonical directories. Without --skip-core, pulls lib/utils/variants from the registry when present (this is how you get utils today).

add

bunx ui8kit add button
bunx ui8kit add button card --force
bunx ui8kit add --all --runtime svelte
bunx ui8kit add button --dry-run
bunx ui8kit add button --registry-url https://unpkg.com/@ui8kit/registry@2.0.0/r --strict-cdn

Install preserves nested paths (e.g. components/ui/button/Button.svelte), no basename flatten.

Runtime filter: when --runtime or config.runtime is set, only that stack’s files are written, plus shared brick assets (*.shared.ts, *.variants.json). Utils/lib items are installed in full when reachable. Items that declare a different item-level runtime field are skipped entirely.

# Multi-file brick on CDN → only Svelte + shared land on disk
bunx ui8kit add button --runtime svelte

Known gap: ui8kit add utils fails in 2.0.1 — use init core install or the manual fallback.

list / diff / info / cache / reset / scan / build

Same roles as v1; info --cdn shows resolved CDN order.

Registry item (contract)

{
"name": "button",
"type": "registry:ui",
"digest": "2.0.0",
"dependencies": [],
"registryDependencies": ["utils", "slot"],
"files": [
{
"path": "ui/button/Button.svelte",
"target": "components/ui/button/Button.svelte",
"content": "..."
},
{
"path": "ui/button/button.variants.json",
"target": "components/ui/button/button.variants.json",
"content": "..."
}
]
}

Breaking changes (v1 → v2)

• framework: "vite-react" → react | svelte | … | none
• init no longer requires Vite + React
• Install paths use {dir}/… + optional paths remap
• File install preserves relative structure (target / path), not basename-only
• New types: registry:utils, registry:widget
• Config fields: dir, runtime, cdnBaseUrls, contractVersion

Registry publish loop

1. Author/kit digest published as registry JSON on a CDN base (@ui8kit/registry)
2. Apps: ui8kit init (with core) + ui8kit add --runtime …
3. Maintainers: pack codegen → ui8kit build → publish r/
4. Tailwind content / @source points at {dir}/**

Development / publish

npm install
npm run type-check
npm test
npm run build
npm run pack:check # dry-run tarball contents# npm publish # after npm login; runs prepublishOnly

Maintainer scripts (local fixtures, CDN probe): see scripts/README.md.

User & author guides: see docs/README.md.
Deferred CLI fixes / known issues: .project/known-issues.md.

License

MIT