Shelf is open source and in early preview
Shelf

For AI agents: the documentation index is at /llms.txt, and any docs page is available as Markdown by appending .md to its URL.

Installation

Set up Shelf in a React project, add components, and check the result.

Shelf needs Node 20.12 or newer, React, and a build that compiles StyleX. 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.

Pick your framework

  • Vite: StyleX through @stylexjs/unplugin. The reference setup.
  • Next.js: StyleX through Babel and PostCSS. This site runs on it.
  • TanStack Start: StyleX through the same Vite plugin. Not yet tested end to end.

The steps below are the same in every framework once StyleX compiles. Each guide covers the StyleX setup for its framework.

Install the 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

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 setup is missing, and it adds a short block to AGENTS.md and a Shelf skill to .agents/skills/shelf/ so coding agents know how to work with Shelf (--no-agents skips both). There is no default registry yet, so pass --registry or set SHELF_REGISTRY.

Add components

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
after shelf add button dialog
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

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.