Installation

CLI Quick Setup

Generate CSS imports and auto-append to your stylesheet:

npx @hareru/cli add Button --write
npx @hareru/cli add Button --write --mode tailwind

The CLI auto-detects your CSS entry file and package manager. CSS mode defaults to per-component when --mode is not specified.

Next.js

1. Install packages

npm install @hareru/tokens @hareru/ui

2. Configure Next.js

Add the following to next.config.ts:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  transpilePackages: ["@hareru/ui", "@hareru/tokens"],
};

export default nextConfig;

3. Import styles

In your globals.css, pick one of:

A. Standalone (includes tokens, reset, and component styles):

@import "@hareru/ui/styles.css";

B. Portable (alongside other frameworks — no global reset):

@import "@hareru/tokens/css";
@import "@hareru/ui/styles/components.css";
@import "@hareru/ui/styles/scope.css"; /* opt-in: .hui-root subtree typography */

C. Tailwind v4 coexistence (recommended for Tailwind projects):

@layer theme, base, hui, components, utilities;
@import "tailwindcss";
@import "@hareru/tokens/css";
@import "@hareru/ui/styles/components.layer.css";
@import "@hareru/ui/styles/scope.css"; /* opt-in */

D. Per-component (minimal bundle):

@import "@hareru/tokens/css";
@import "@hareru/ui/styles/components/Button.css";
@import "@hareru/ui/styles/components/Card.css";
/* Add @hareru/ui/styles/animations.css when using StreamingText, ReasoningPanel, or ToolCallCard */

styles.css already bundles tokens, so @hareru/tokens/css is not needed when using it.

If your host app has no CSS reset, optionally add @import "@hareru/ui/styles/baseline.css" for box-sizing: border-box and form element font inheritance.

4. Add providers

// app/providers.tsx
"use client"

import { ThemeProvider, Toaster } from "@hareru/ui"

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider defaultTheme="system">
      {children}
      <Toaster />
    </ThemeProvider>
  )
}

// app/layout.tsx
import { Providers } from "./providers"
import "./globals.css"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

Vite

1. Install packages

npm install @hareru/tokens @hareru/ui

2. Import styles

In your entry CSS file, pick one of the patterns above (A–D). For example:

A. Standalone (Hareru-only app):

@import "@hareru/ui/styles.css";

C. Tailwind v4 coexistence:

@layer theme, base, hui, components, utilities;
@import "tailwindcss";
@import "@hareru/tokens/css";
@import "@hareru/ui/styles/components.layer.css";

3. Add providers

// src/App.tsx
import { ThemeProvider, Toaster } from "@hareru/ui"

function App() {
  return (
    <ThemeProvider defaultTheme="system">
      {/* Your app */}
      <Toaster />
    </ThemeProvider>
  )
}

Local Development (Monorepo)

If you're using Hareru UI as a local dependency:

// package.json
{
  "@hareru/tokens": "file:../hareru-ui/packages/tokens",
  "@hareru/ui": "file:../hareru-ui/packages/ui"
}

Run pnpm build inside the hareru-ui directory first to generate the dist output.

For Next.js with Turbopack, add:

import path from "path";

const nextConfig: NextConfig = {
  turbopack: {
    root: path.join(__dirname, ".."),
  },
  transpilePackages: ["@hareru/ui", "@hareru/tokens"],
};

On this page