Getting started

Installation

Junco needs Tailwind CSS v4. Pick your setup below; each takes a couple of minutes.

Create an app with Tailwind

npx create-next-app@latest my-app --tailwind --app

Install Junco
```
npm i junco @junco/tailwind
```

Import the styles

Replace the contents of app/globals.css:

app/globals.css

@import "tailwindcss";
@import "@junco/tailwind";

/* Let Tailwind see the classes junco's components use */
@source "../node_modules/junco/dist";

Add the theme provider

themeScript() applies the saved theme before first paint, so dark mode never flashes. Import it from junco/server, which also has cn() and every *Variants helper for server components.

app/layout.tsx

import { ThemeProvider } from "junco";
import { themeScript } from "junco/server";
import "./globals.css";

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <script dangerouslySetInnerHTML={{ __html: themeScript() }} />
      </head>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

Use a component

app/page.tsx

import { Button } from "junco";

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

Server components#

junco is a client module, so in a React Server Component its exports are client references: you can render <Button>, but you can't call cn() or buttonVariants() there. Import those helpers from junco/server instead. It has no "use client" and is checked in CI to load under React's server build.

import { buttonVariants, cn, themeScript } from "junco/server";
import Link from "next/link";

// A link styled as a button, rendered on the server
<Link href="/pricing" className={buttonVariants({ variant: "outline" })}>Pricing</Link>

Export	Description
`cn`	Merge class names and resolve Tailwind conflicts.
`themeScript`	The no-flash inline script for <head>.
`applyTheme`	Set .dark, data-theme, data-motion and color-scheme on an element.
`buttonVariants, badgeVariants, cardVariants, spinnerVariants, emptyStateVariants`	Class builders for styling your own elements like Junco components.

Fonts#

Junco is designed around Geist and Geist Mono. The tokens fall back to the system font, so loading them is optional. In Next.js, install the geist package and point the tokens at it:

:root {
  --font-sans: var(--font-geist-sans), ui-sans-serif, system-ui, sans-serif;
  --font-mono: var(--font-geist-mono), ui-monospace, monospace;
}

Already using shadcn/ui?#

Junco's token names match shadcn's (--background, --primary, --muted-foreground and so on), so your existing shadcn components pick up Junco's theme as soon as you import @junco/tailwind.