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 checkIt 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/uiNeeds 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
| Symptom | Likely cause |
|---|---|
| Components render unstyled | Tailwind is not scanning @shavin/ui. Check the content entry (v3) or the @source line (v4) below. |
| Colours are wrong or missing in dark mode | The app is not inside ThemeProvider, or the Shavin stylesheet is not imported. |
| Helpers like cn throw in a Server Component | Import helpers from @shavin/ui/server in files without "use client". |
| The agent can't see Shavin tools | The MCP server is not registered, or the editor needs a restart. See MCP setup. |
| get_live_audit returns nothing | The bridge is not running, or the page is not open in a browser. Start it with npx @shavin/cli bridge. |