Installation

Starting a new app with create-buttery, adding buttery to an app you have with buttery init, working in buttery's repository, and what an app on buttery is made of.

There are three ways in. create-buttery starts a new app in any folder, from one of four templates. buttery init adds buttery to a React app you have. And buttery's repository, which is public on GitHub, has the starter, the templates and the demos side by side, for working on buttery itself.

Start a new app

npx create-buttery my-app
cd my-app
npm run dev

create-buttery makes my-app in the folder you're in from the blank template and installs it with the package manager that ran it, so pnpm create buttery my-app installs with pnpm. --template dashboard, editor or marketing starts from another template, and --desktop adds the Tauri shell, so the app also opens as a desktop window. It needs Node 22 or later.

The app comes with buttery's lint configs, Playwright and @butteryui/test with its own specs, the buttery command, and what coding agents read. Command line has everything the command does.

Add it to an app you have

npx buttery init

init adds buttery's packages to the app and installs them, imports @butteryui/core/styles.css and @butteryui/react/styles.css at its entry and wraps it in ButteryProvider, writes buttery's ESLint and stylelint configs when the app has none, and gives coding agents an AGENTS.md section, the skill and the MCP server. What it can't do for certain it lists, with how. npx buttery doctor then checks the setup and says how to fix what isn't right.

To do the same by hand:

pnpm add @butteryui/core @butteryui/react lucide-react
pnpm add -D @butteryui/test @butteryui/lint

Import @butteryui/core/styles.css and @butteryui/react/styles.css once at the app's entry and wrap it in ButteryProvider, as the starter's entry under What's in the app does. The app needs React 19; @butteryui/test runs in Playwright, and @butteryui/lint plugs into ESLint 9 and stylelint 16.

Work in buttery's repository

A clone, an install and one command give you an app on the web and in a desktop window, in about five minutes.

What you need

• Node 22.18 or later

  Or 24.11 and later on the 24 line, or 26 and later: the engines range in the root package.json.

• pnpm 12

  On Node 22 and 24, corepack enable installs the pinned 12.14.0. Node 26 has no Corepack, so run npm install -g pnpm@12.14.0.

• Git

  To clone the repository. It's public, so you don't need an account or a key.

For the desktop app you also need Rust, through rustup, and on macOS the Xcode Command Line Tools (xcode-select --install), which Tauri v2 builds with.

1. Clone the repository

   bash

   git clone https://github.com/aliboIly/buttery.git
   cd buttery

2. Install everything

   bash

   pnpm install

   This installs every package and app in the repository and turns on its git hooks.

3. Copy the starter

   bash

   pnpm new-app my-app

   pnpm new-app copies apps/starter to apps/my-app, gives the copy its name and the next free port, and installs it. To start from a template instead, add its flag:

   • Blank

     The starter on its own, a Vite and React app wired up for buttery with a desktop shell, and nothing on the screen yet.

     --template blank
   • Dashboard

     A web app with a sidebar, an overview of the week's numbers, a table of orders with a page for each, products, search, settings with a plan page, and a sign-in screen, made from the App kit.

     --template dashboard
   • Editor

     A web app for making one thing at a time, with a header bar, the work on a stage and an inspector of its settings, made from the inspector pattern.

     --template editor
   • Marketing

     A one-page site with a sticky bar, a hero, sections for what a product does and what it costs, and a footer, made from the page patterns.

     --template marketing

4. Start it

   bash

   pnpm --filter my-app dev

   Open the address it prints. The app already loads buttery's styles and sits in ButteryProvider, and in development LayoutGuard outlines anything that overlaps or overflows.

5. Open it as a desktop app

   bash

   pnpm --filter my-app tauri dev

   The starter is also a Tauri v2 app, so the same code opens in a window of its own. Desktop apps says what changes there.

What's in the app

An app on buttery needs two stylesheets, imported once at its entry, and ButteryProvider around everything. This is the starter's entry, as pnpm new-app copies it:

import "@butteryui/core/styles.css";
import "@butteryui/react/styles.css";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { ButteryProvider } from "@butteryui/react";
import { App } from "./App.tsx";

const container = document.getElementById("root");
if (!container) throw new Error("index.html needs a #root element.");

createRoot(container).render(
  <StrictMode>
    <ButteryProvider>
      <App />
    </ButteryProvider>
  </StrictMode>,
);

ButteryProvider sets the color scheme, the density and the motion preference for everything inside it, and mounts the layers that menus, dialogs and toasts open into.

These are the packages in the starter's package.json. Inside the repository, the @butteryui/* packages come from the workspace.