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

Next.js

Set up Shelf in a Next.js project.

Create a project

npx create-next-app@latest my-app --typescript --src-dir

Skip this if you already have a Next.js project. This site runs on Next with Shelf, so the steps below are the ones it uses.

Set up StyleX

bun add @stylexjs/stylex

bun add -d @stylexjs/babel-plugin @stylexjs/postcss-plugin

Next compiles StyleX with Babel and writes the CSS with PostCSS. Add babel.config.js:

babel.config.js

const path = require("node:path");

module.exports = {
  presets: ["next/babel"],
  plugins: [
    [
      "@stylexjs/babel-plugin",
      {
        dev: process.env.NODE_ENV === "development",
        runtimeInjection: false,
        treeshakeCompensation: true,
        // Match the aliases in tsconfig.json.
        aliases: { "@/*": [path.join(__dirname, "src/*")] },
        unstable_moduleResolution: { type: "commonJS" },
      },
    ],
  ],
};

Add postcss.config.js, reusing the same Babel plugins:

postcss.config.js

const babelConfig = require("./babel.config");

module.exports = {
  plugins: {
    "@stylexjs/postcss-plugin": {
      include: ["src/**/*.{js,jsx,ts,tsx}"],
      babelConfig: {
        babelrc: false,
        parserOpts: { plugins: ["typescript", "jsx"] },
        plugins: babelConfig.plugins,
      },
      useCSSLayers: true,
    },
  },
};

Add the @stylex directive where the generated CSS should go, once, in the stylesheet your root layout imports.

src/app/globals.css

@stylex;

A babel.config.js makes Next use Babel instead of SWC for your source, so builds are somewhat slower.

Install the CLI

bun add -d @shelfui/cli

The package is @shelfui/cli and its command is shelf.

Initialize Shelf

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

Writes shelf.config.json and .shelf/lock.json, copies the path aliases from your tsconfig.json, and adds a short agent block to AGENTS.md and a Shelf skill to .agents/skills/shelf/. It warns about anything missing from the StyleX setup above.

Add components

bunx shelf add button

Copies Button, the foundations it uses, and the packages it needs into your project, then records what it installed. The files are yours to edit. See ownership and provenance.

Check the result

bunx shelf check

Verifies config, provenance, and imports. Your own build still covers the rest. See validation.

Use a component

src/app/page.tsx

import { Button } from "@/components/ui/button";

export default function Page() {
  return <Button>Save</Button>;
}

Interactive components ship with "use client" where they need it, so you can import them from server components. For fonts, Shelf reads --font-sans and --font-mono, which works with next/font. See installation.