Installation

Prerequisites

Litefy does not provide a full project scaffold. Use it in an existing React project.

Your project needs to meet the following requirements:

• React 19+ (relies on new React 19 features; older versions are incompatible)
• Tailwind CSS v4 — components are styled with Tailwind utilities; no tailwind.config is needed, the design token layer ships as CSS
• TypeScript enabled
• Path alias @/* configured to point to the root of your source code

Component templates import cn and sibling parts from the relative barrel .., and init generates utils/cn.ts up front — so the utils directory always sits next to the components directory and no alias configuration is required. See your build tool's documentation for how to configure the @/* alias for your own code.

Quick Start

Four steps: initialize, install the required styles plus your first components, import the global style entry, and use it.

1. Initialize

Run the init command (package-manager variants in Commands below). It generates the litefy.json config, creates the ui/litefy directory, installs react, react-dom, lucide-react, tailwindcss and tailwind-merge, downloads the required base style theme.css, and writes the auto-generated global style entry styles/index.css.

src/ui/litefy/
├── index.ts           # aggregate barrel — import components from here
├── components/        # installed components, one standalone file each
├── utils/             # cn and headless hooks
└── styles/index.css   # global style entry, rewritten automatically by the CLI

2. Install optional styles and components

theme.css (the required token layer) is already installed by init. interactive.css — the global disabled/focus/press behavior layer — is recommended but optional: skip it if you would rather implement your own interaction styles. See Styles for the full layer list and the optional brand/surface presets.

Add them together with your first components using the add command, e.g. add style-interactive button.

Every add rewrites styles/index.css to match what is installed — you never edit it by hand.

3. Import the global style entry

In your JS/TS entry file (e.g. main.tsx). Without this line the token layer and the interactive layer never load:

import "@/ui/litefy/styles/index.css";

4. Use it

import { Button } from "@/ui/litefy";

<Button onClick={() => console.log("clicked")}>Click me</Button>

Commands

init

Initialize your project: generate the litefy.json config file, create the ui/litefy directory structure, generate utils/cn.ts and the aggregate barrel, install the dependencies, download the required style-theme base style, and initialize the global style entry styles/index.css. Running add before initialization triggers the initialization flow automatically.

⚠️ Do not manually modify the path fields in litefy.json. If you change the paths yourself, you must keep the project alias and import statements in sync; the CLI will not fix them automatically.

npx litefy@latest init

yarn dlx litefy@latest init

pnpm dlx litefy@latest init

bunx --bun litefy@latest init

Options

• -y, --yes: Skip interactive prompts and use all default configuration

add

Download and install components and their corresponding hooks and utils in batch, automatically resolve each entry's dependence (detected by scanning every template's relative imports at build time; cn is generated by init and never needs resolving), install the resolved npm dependencies, and update the aggregate export file and the styles/index.css entry.

npx litefy@latest add <components...>

yarn dlx litefy@latest add <components...>

pnpm dlx litefy@latest add <components...>

bunx --bun litefy@latest add <components...>

Options

• -o, --overwrite: Force overwrite existing component files
• -y, --yes: Skip interactive prompts

install

Install all registry entries in one go — useful to pull the full library locally. Delegates to add, so dependencies are resolved and exports/styles are updated the same way.

npx litefy@latest install

yarn dlx litefy@latest install

pnpm dlx litefy@latest install

bunx --bun litefy@latest install

Options

• -o, --overwrite: Force overwrite existing component files
• -y, --yes: Skip interactive prompts

rm

Remove installed components: delete the corresponding files and update the config manifest and aggregate exports.

npx litefy@latest rm <names...>

yarn dlx litefy@latest rm <names...>

pnpm dlx litefy@latest rm <names...>

bunx --bun litefy@latest rm <names...>

repair

Validate the integrity of local resources, fetch missing components and hooks online, and regenerate aggregate exports.

npx litefy@latest repair

yarn dlx litefy@latest repair

pnpm dlx litefy@latest repair

bunx --bun litefy@latest repair

clean

Offline cleanup: prune component records in the config that no longer exist locally. No network required.

npx litefy@latest clean

yarn dlx litefy@latest clean

pnpm dlx litefy@latest clean

bunx --bun litefy@latest clean

uninstall

Completely uninstall: delete all Litefy local files and litefy.json. Hand-written imports in your business code are not removed automatically; clean them up manually.

npx litefy@latest uninstall

yarn dlx litefy@latest uninstall

pnpm dlx litefy@latest uninstall

bunx --bun litefy@latest uninstall