lumora

Installer CLI for Lumora UI — premium, motion-first React components. Interfaces that glow.

Components are distributed as source: lumora add copies the .tsx files (plus the small shared lib files they rely on) straight into your project and rewrites their imports to your aliases. You own the code; there is no runtime dependency on this package.

Requirements

• Node >= 18.18
• A React project with Tailwind CSS
• motion, clsx, tailwind-merge, class-variance-authority (lumora init prints the exact install command for your package manager)

Quick start

npx lumora-ui@latest init
npx lumora-ui@latest add button animated-tooltip icon/mail block/hero

Commands

lumora init

Sets your project up:

• detects your package manager from the lockfile (pnpm / yarn / bun / npm) and prints the dependency install command
• writes lumora.json (see Configuration)
• creates the component and icon directories
• copies the lumora.css design tokens into your component directory
• prints how to wire the tokens into your global stylesheet and make sure Tailwind scans the installed files

npx lumora-ui@latest init

Pass --overwrite to refresh a previously copied lumora.css.

lumora add <name...>

Copies one or more registry entries into your project, including any internal dependencies they declare (lib/cn.ts, lib/motion.ts, lib/icon.tsx, or other components a block builds on). Relative imports are rewritten to your configured aliases — e.g. ../lib/cn becomes @/components/lumora/lib/cn.

Names are addressed by category:

| Category | Name format | Installed to | | ---------- | ------------------ | ----------------------------- | | component | button | components/lumora/ | | block | block/hero | components/lumora/blocks/ | | ai | ai/chat-widget | components/lumora/ai/ | | icon | icon/mail | components/icons/ |

npx lumora-ui@latest add button
npx lumora-ui@latest add block/hero ai/command-menu icon/mail
npx lumora-ui@latest add button --overwrite   # replace existing files

Existing files are never replaced unless you pass --overwrite. After copying, the CLI lists any npm packages the new components import so you can install whatever is still missing.

lumora list

Pretty-prints everything in the registry, grouped by category, with each component's one-line description.

npx lumora-ui@latest list

Configuration (lumora.json)

Created by lumora init at your project root:

{
  "componentDir": "components/lumora",
  "iconDir": "components/icons",
  "aliases": {
    "components": "@/components/lumora",
    "icons": "@/components/icons"
  }
}

• componentDir — where components land (blocks in blocks/, AI components in ai/, shared lib files in lib/)
• iconDir — where animated icons (and their shared lib/icon.tsx) land
• aliases — what rewritten imports look like in the copied files; adjust to match your tsconfig.json paths

lumora add finds lumora.json by walking up from the current directory, so it works from anywhere inside your project.

Registry resolution

The CLI reads registry/registry.json (an index of names, paths, and dependency metadata) and fetches file contents from the same base:

1. LUMORA_REGISTRY environment variable — a registry.json URL or local file path; file contents resolve relative to it
2. the published registry on GitHub (default)
3. a local registry/registry.json — automatic fallback when you run the CLI inside a Lumora UI checkout (development)

LUMORA_REGISTRY=/path/to/lumora-ui/registry/registry.json npx lumora list

Development notes

The CLI is implemented directly in bin/lumora.js as modern ESM JavaScript with JSDoc types — that file is the single source of truth (no src/, no build step). pnpm typecheck runs tsc --noEmit over it with checkJs against the strict workspace tsconfig.

The registry itself is generated by node scripts/build-registry.mjs at the repo root — see registry/README.md.