Skip to content

Debug setup

If npx @shavin/cli init could not finish a step, or you prefer to set Shavin up by hand, this page has each step and the usual problems.

Run the check first

npx @shavin/cli check

It checks Node, React and package versions, the stylesheet imports, the Tailwind setup, ThemeProvider and the agent files, and gives a fix for each problem. npx @shavin/cli doctor is the same command. Add --json for machine output; it exits with an error when a check fails, so you can run it in CI. Agents get the same report from the MCP tool inspect_environment.

1. Install

npm install @shavin/ui

Needs React 19 and Tailwind CSS 3.4 or 4. Icons and class helpers come with the package.

2. Connect Tailwind 4

In your global CSS, after @import "tailwindcss". Tailwind 4 skips node_modules, so the @source line is required; adjust the relative path to your CSS file.

@import "tailwindcss";
@import "@shavin/ui/tokens.css";
@import "@shavin/ui/base.css" layer(base);
@import "@shavin/ui/theme-v4.css";
@source "../node_modules/@shavin/ui";

For OKLCH colours, import global-oklch.css and theme-v4-oklch.css instead.

2. Or connect Tailwind 3

// tailwind.config.ts
import shavinPreset from "@shavin/ui/tailwind-preset";

export default {
  presets: [shavinPreset],
  content: [
    "./node_modules/@shavin/ui/**/*.{js,mjs,ts,tsx}",
    "./app/**/*.{ts,tsx}",
    "./components/**/*.{ts,tsx}",
  ],
};

Then import @shavin/ui/styles.css in your global CSS.

3. Wrap the app

// app/layout.tsx
import { ThemeProvider } from "@shavin/ui";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider brandColor="#0F766E">{children}</ThemeProvider>
      </body>
    </html>
  );
}

The brand colour is optional. See Theme system for the other props.

Common problems

SymptomLikely cause
Components render unstyledTailwind is not scanning @shavin/ui. Check the content entry (v3) or the @source line (v4) below.
Colours are wrong or missing in dark modeThe app is not inside ThemeProvider, or the Shavin stylesheet is not imported.
Helpers like cn throw in a Server ComponentImport helpers from @shavin/ui/server in files without "use client".
The agent can't see Shavin toolsThe MCP server is not registered, or the editor needs a restart. See MCP setup.
get_live_audit returns nothingThe bridge is not running, or the page is not open in a browser. Start it with npx @shavin/cli bridge.
Configure Theme
Theme
Brand Color
Custom
Gray Family
Appearance
Radius
Scaling
Panel Style
Heading Font
Body Font