hunjy-ui

hunjy-ui

Eine moderne CLI, die React- + Tailwind-CSS-Komponenten (Radix UI + Lucide Icons) direkt als Quellcode in dein Projekt bringt – im Stil von shadcn/ui. Kein npm install einer Komponentenbibliothek: du bekommst die .tsx-Dateien in src/components/ui/, kannst sie frei anpassen und behältst die volle Kontrolle.

Schnellstart

In einem bestehenden React + TypeScript-Projekt:

npx hunjy-ui init

init erkennt dein Framework automatisch und richtet es passend ein:

Framework	Config-Datei	Tailwind-Integration	CSS-Datei
Vite	vite.config.ts	@tailwindcss/vite-Plugin	src/index.css (o.ä.)
Next.js (App- oder Pages-Router)	postcss.config.mjs	@tailwindcss/postcss	app/globals.css / styles/globals.css
Astro	astro.config.mjs	@tailwindcss/vite-Plugin	src/styles/global.css

In jedem Fall richtet init ein:

• components.json (Konfiguration: Pfade & Aliase)
• src/lib/utils.ts (cn()-Helper auf Basis von clsx + tailwind-merge)
• Tailwind-v4-Theme (CSS-Variablen für Farben, Radius, Dark Mode) in deiner globalen CSS-Datei – falls die Datei bereits ein eigenes Theme enthält (z. B. Next.js' Standard-globals.css), wird unser Theme angehängt statt vorangestellt, damit es nicht von den vorhandenen Variablen überschrieben wird
• Den Pfad-Alias @/* in der passenden tsconfig
• Basis-Dependencies (tailwindcss, das framework-spezifische Tailwind-Paket, tw-animate-css, class-variance-authority, clsx, tailwind-merge)

Jeder Schritt wird als Checkliste mit Live-Status angezeigt. Wird ein Config-Muster nicht automatisch erkannt (z. B. bei stark angepassten Configs), zeigt init den nötigen Code-Schnipsel zum manuellen Eintragen an, statt die Datei zu beschädigen.

Dabei fragt init interaktiv:

• Farbmodus: Light & Dark (mit .dark-Umschalter), nur Light oder nur Dark
• Farben: Standard-Palette (Graustufen-Theme) oder eigene Hex-Farben für Primär-, Sekundär-, Hintergrund-, Akzent- und Fehlerfarbe – alle abhängigen Töne (Vordergrund, Muted, Border, …) werden automatisch mit ausreichendem Kontrast berechnet

Mit -y/--yes werden alle Rückfragen übersprungen und die Standard-Palette mit Light & Dark verwendet.

Danach Komponenten hinzufügen:

npx hunjy-ui add button dialog card
# oder alle auf einmal:
npx hunjy-ui add all
# ohne Argumente: interaktive Mehrfachauswahl
npx hunjy-ui add

Jede Komponente landet unter src/components/ui/<name>.tsx. Benötigte npm-Pakete (z. B. radix-ui, lucide-react) sowie abhängige Komponenten (z. B. installiert drawer automatisch auch dialog) werden dabei automatisch aufgelöst und installiert – als Checkliste mit Live-Status pro Datei und Paket.

Astro-Hinweis: Astro unterstützt mehrere UI-Frameworks parallel. init/add richten Tailwind und die Komponenten-Dateien ein, aber die React-Rendering-Unterstützung (@astrojs/react) musst du selbst installieren, falls noch nicht vorhanden: npx astro add react. Erst danach lassen sich die Komponenten als Islands (<Button client:load />) in .astro-Dateien einsetzen.

Alle verfügbaren Komponenten anzeigen:

npx hunjy-ui list

Theme nachträglich anpassen

npx hunjy-ui theme <spec> schreibt dein Farbschema neu, ohne init erneut durchlaufen zu müssen. <spec> ist Base64-kodiertes JSON (rohes JSON funktioniert testweise auch):

node -e "console.log(Buffer.from(JSON.stringify({
  mode: 'both',
  radius: '0.5rem',
  colors: { primary: '#4f46e5', secondary: '#f4f4f5', background: '#ffffff', accent: '#f4f4f5', destructive: '#dc2626' }
})).toString('base64'))"
# -> ey... (Ausgabe als <spec> verwenden)

npx hunjy-ui theme ey...

Alle Felder sind optional (fehlende Farben fallen auf die Standard-Palette zurück). Kontrast-Farben, Muted-/Border-/Ring-Töne werden wie bei init automatisch berechnet. Praktisch: Beschreibe dein Wunsch-Theme in Worten gegenüber deinem AI-Assistenten ("mach mir ein dunkles Cyberpunk-Theme mit Neon-Lila") – der Assistent kann daraus die passenden Hex-Werte ableiten, das Spec-JSON base64-kodieren und dir direkt den fertigen npx hunjy-ui theme ...-Befehl liefern.

Verwendung

import { Button } from "@/components/ui/button";
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";

function App() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Willkommen</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Loslegen</Button>
      </CardContent>
    </Card>
  );
}

Dark Mode

Theme-Variablen + .dark-Klassen-Strategie (wie shadcn). Aktivieren durch Hinzufügen der Klasse dark auf einem Vorfahren-Element (z. B. <html class="dark">).

Theme anpassen

Alle Farben sind CSS-Variablen (--ui-*) in :root / .dark, direkt in deiner globalen CSS-Datei editierbar:

:root {
  --ui-primary: oklch(0.55 0.2 260);
  --ui-radius: 0.5rem;
}

Verfügbare Komponenten (42)

• Layout: container, stack, grid, divider
• Typografie: typography (Heading, Text), kbd
• Feedback: alert, badge, progress, spinner, skeleton, toast
• Datenanzeige: card, table, avatar
• Formulare: button, label, input, textarea, checkbox, radio-group, switch, select, toggle, toggle-group, slider
• Navigation: tabs, dropdown-menu, navbar, sidebar, footer, breadcrumb, pagination
• Overlays: dialog, alert-dialog, drawer, popover, hover-card, tooltip, accordion, collapsible, scroll-area

Alle interaktiven Komponenten basieren auf Radix UI Primitives (Fokus-Management, Tastatursteuerung, ARIA inklusive). Icons: Lucide.

Blocks (Templates)

Zusätzlich zu den einzelnen Komponenten gibt es fertige, aus mehreren Komponenten zusammengesetzte Blocks – Startpunkte, die du direkt kopierst und anpasst. Sie landen unter src/components/blocks/ (statt src/components/ui/):

• dashboard-shell – Seiten-Layout mit Sidebar-Navigation und Kopfzeile
• login-form – Anmeldeformular in einer Card
• settings-dialog – Formular innerhalb eines Dialogs (Formular im Overlay)
• confirm-dialog – wiederverwendbarer Bestätigungs-Dialog für zerstörerische Aktionen

npx hunjy-ui add dashboard-shell

CLI-Befehle

Befehl	Beschreibung
hunjy-ui init [-y] [-c <dir>]	Projekt einrichten (Framework-Erkennung, Theme, Utils, Alias, Basis-Deps)
hunjy-ui add [namen...|all] [-y] [-o]	Komponenten und Blocks hinzufügen. Ohne Namen: interaktive Auswahl. -o überschreibt vorhandene Dateien
hunjy-ui list	Alle verfügbaren Komponenten und Blocks auflisten

Entwicklung an hunjy-ui selbst

Dieses Repository enthält sowohl die "Master"-Quellen der Komponenten (src/components/ui/) als auch die daraus generierte CLI-Registry.

npm install
npm run storybook       # Komponenten-Vorschau unter http://localhost:6006
npm run registry:build  # generiert src/registry/data.ts aus src/components/ui/*
npm run build            # registry:build + CLI-Bundle nach dist/cli.js
npm run typecheck

Neue Komponente hinzufügen: Datei unter src/components/ui/<name>.tsx anlegen (Imports über @/lib/utils bzw. @/components/ui/...), Eintrag in src/registry/manifest.ts ergänzen, npm run registry:build laufen lassen.

Lokal testen (vor der Veröffentlichung)

npx hunjy-ui funktioniert erst, nachdem das Paket auf npm veröffentlicht wurde – vorher lädt npx versucht es von der npm-Registry herunterzuladen und schlägt mit 404 Not Found fehl. Zum lokalen Testen zwei Möglichkeiten:

a) Direkt aufrufen:

npm run build
node dist/cli.js init --cwd /pfad/zu/deinem/projekt
node dist/cli.js add button --cwd /pfad/zu/deinem/projekt

b) Global verlinken (dann wie im echten Betrieb per Befehlsname nutzbar):

npm run build
npm link                      # einmalig hier im hunjy-ui-Verzeichnis
cd /pfad/zu/deinem/projekt
npm link hunjy-ui             # einmalig im Zielprojekt
hunjy-ui init
hunjy-ui add button

Veröffentlichen auf npm

npm run build
npm publish --access public

Danach nutzbar per npx hunjy-ui init.