Installation

Install the CLI, point it at a registry, add what you need, and check it.

Shelf needs Node 20.12 or newer, React, and a Vite app compiled with @stylexjs/unplugin. It works with npm, pnpm, yarn, and Bun, and uses the one your project's lockfile names. Components depend on Base UI and StyleX, which shelf add installs for you.

Install the CLI

bun add -d @shelfui/cli

The package is @shelfui/cli and its command is shelf. Install it first: the npm package named shelf is unrelated, so running npx shelf without it installs something else.

Set up a project

bunx shelf init --registry <path-or-url>

init writes shelf.config.json and .shelf/lock.json. If your tsconfig.json declares path aliases such as @/*, it copies them, so installed files import the way your app does. It warns when the StyleX Vite plugin is missing. There is no default registry yet, so pass --registry or set SHELF_REGISTRY.

Add components

bunx shelf add button dialog

Shelf resolves the items and the Shelf items they build on, copies the files, installs the packages they need, and records what it installed.

terminal

$ shelf add button dialog
✓ resolved button, dialog, foundations, utils, icons
✓ added 8 files
✓ recorded provenance in .shelf/lock.json

Button, Dialog, Foundations, Utils and Icons are now yours.

The output of shelf add button dialog.

after shelf add button dialog

src/
├── components/ui/
│   ├── button.tsx
│   ├── dialog.tsx
│   └── icons.tsx
├── styles/shelf/
│   ├── tokens.stylex.ts
│   ├── conditions.stylex.ts
│   ├── themes.ts
│   └── fonts.css
└── lib/shelf/
    └── utils.ts
.shelf/
├── lock.json          revision and hash of every file
└── base/              the files exactly as installed
shelf.config.json

After shelf add button dialog: components in src/components/ui, foundations in src/styles/shelf, helpers in src/lib/shelf, and provenance in .shelf.

Commit all of it, including .shelf/. That record is how Shelf tells your changes apart from what it installed.

Change them

Edit the files like any other source. shelf add never overwrites a file you changed unless you pass --overwrite. Read ownership and provenance for the details.

Use your own fonts

Foundations read the typefaces from --font-sans and --font-mono, and fall back to Geist from fonts.css. With next/font, set variable: "--font-sans" on your font and add its variable class to <html>. Then delete fonts.css and its import. No Shelf file needs editing.

Check your install

bunx shelf check

Checks that what Shelf installed is intact and lists what you changed. Your own TypeScript, lint, and build keep covering the code. See validation.

Removing Shelf

Delete shelf.config.json, .shelf/, and the @shelfui/cli package. The components keep working, because they are your code.