Quick Start

Quick Start

Get your first animated component installed in about five minutes.

Prerequisites

Requirement	Notes
Node.js >= 20	To use the CLI. Repo development needs Node >= 22 + pnpm.
A React project	Next.js, Vite, Remix, or similar — with TypeScript and Tailwind CSS.
tsconfig.json with path aliases	e.g. @/*. init reads them; it never modifies them.

Windows? The CLI itself runs anywhere, but repo shell scripts expect WSL2 or Git Bash with LF line endings (see FAQ).

1. Initialize your project

# One-shot, no install:
npx @framebits/cli init

init detects your package manager (pnpm/yarn/npm/bun), framework (including Next.js app/pages router), TypeScript setup, Tailwind version (v3 config file vs v4 @import "tailwindcss"), src/ layout, and existing import aliases — then writes framebits.json. Running it twice never corrupts anything.

# Non-interactive (CI-friendly):
npx @framebits/cli init --yes

2. Add a component

npx @framebits/cli add aurora-text

What happens, in order:

1. The component JSON is fetched from the registry and validated.
2. Its SHA-256 hash is recomputed — any tampering aborts with exit 4 and nothing is written.
3. Registry dependencies resolve recursively (aurora-text pulls in cn).
4. Files land under your configured aliases (e.g. @/components/ui).
5. Tailwind keyframes/animation and CSS variables are merged into your CSS.
6. Missing npm packages are installed with your package manager.
7. framebits.json records the installed version + hash.

Preview first, change nothing:

framebits add aurora-text --dry-run

3. Verify

# The files exist where your aliases point, e.g:
ls src/components/ui/aurora-text.tsx src/lib/cn.ts
# Your CSS gained a managed block:
grep "framebits:begin aurora-text" src/index.css

Troubleshooting

Symptom	Fix
init hasn't been run	Run framebits init first — add exits 2 without framebits.json.
File conflicts	Re-run with --overwrite, or answer per-file when prompted.
404 component not found	Check the spelling — the CLI suggests the closest match.
Hash/integrity error (exit 4)	Do not bypass. Re-run; if it persists, report it.
Offline / DNS / timeout	Exit 3. Check connectivity or point --registry at a local mirror.

Next: CLI Reference for every flag and exit code · FAQ for the rest.