Installation

Start fresh

Create a new Astro project with Bearnie pre-configured:

The scaffolder asks for a base color (grays) and an accent color (primary) — see themes in the CLI docs for the full list. Skip the prompts with a flag, e.g. --theme=slate-blue.

Then navigate to your project and start developing:

cd my-app
npm install
npm run dev

Every scaffold includes a bearnie.json config at the project root, so the CLI works without running bearnie init first.

Full install

Want all components included from the start? Use the --full flag:

npx create-bearnie my-app --full

This fetches all components from the registry, installs them in src/components/bearnie/, and adds a barrel export at src/components/bearnie/index.ts. Great for exploring or prototyping.

Add to existing project

Run the init command to configure your existing Astro project:

Add the theme styles:

Import the styles in your main CSS file:

@import "tailwindcss";
@import "./bearnie.css";

Then add any component:

When you add interactive components, Bearnie installs shared runtime helpers under src/utils/runtime/ automatically. No manual runtime wiring is needed.

Barrel imports

After adding components, install the barrel export for named imports from a single path:

---
import { Button, Card, CardHeader, CardTitle } from "@/components/bearnie";
---

<Card>
  <CardHeader>
    <CardTitle>Welcome</CardTitle>
  </CardHeader>
  <Button>Get started</Button>
</Card>

Run bearnie add barrel after your components are installed. The --full scaffold includes the barrel automatically.

Manual setup

1. Add the cn utility

Create src/utils/cn.ts:

export function cn(...classes: (string | undefined | null | false)[]): string {
  return classes.filter(Boolean).join(' ');
}

2. Configure path aliases

Add to your tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

3. Add theme styles

Add the styles via CLI:

Then import in your main CSS file:

@import "tailwindcss";
@import "./bearnie.css";

4. Add components

Use the CLI or copy components from src/components/bearnie/ to your project.

src/
├── components/
│   └── bearnie/
│       ├── index.ts
│       ├── button/
│       │   └── Button.astro
│       └── card/
│           ├── Card.astro
│           ├── CardHeader.astro
│           └── CardContent.astro
├── styles/
│   └── bearnie.css
└── utils/
    └── cn.ts

Interactive components (dialog, popover, tabs, …) also install just the runtime modules they need under src/utils/runtime/.

Updating components

Components and styles are copied to your project. You own them. They don’t auto-update when Bearnie releases changes.

See what changed between your files and the registry:

Then pull the latest versions when you’re ready:

update shows what will change and asks before writing — if you’ve customized a component, review the diff first and merge manually where needed.

This is intentional. You control when updates happen and what gets changed.