.skin

Installation

Set up .skin in a new or existing Next.js project in under five minutes.

Prerequisites

Make sure your project meets these requirements before installing .skin.

DependencyVersion
Node.js18+
React18 or 19
Next.js14+
Tailwind CSS3 or 4

01Create a Next.js project

If you're starting from scratch, scaffold a new Next.js app with the App Router and Tailwind CSS enabled:

npx create-next-app@latest my-app \
  --typescript \
  --tailwind \
  --app \
  --src-dir

cd my-app

Skip this step if you're adding .skin to an existing project.

02Install peer dependencies

.skin is built on Radix UI and class-variance-authority. Install shared peer dependencies first, then add the components for your chosen tier. The example below installs the Tier 1 (Micro) set:

# Shared utilities (all tiers)
npm install class-variance-authority clsx tailwind-merge lucide-react

# Radix UI primitives for Tier 1 (Micro)
npm install \
  @radix-ui/react-label \
  @radix-ui/react-slot \
  @radix-ui/react-switch \
  @radix-ui/react-tooltip \
  @radix-ui/react-navigation-menu \
  @radix-ui/react-avatar \
  @radix-ui/react-separator

See the Getting Started page for a full list of packages per tier.

03Copy component files

.skin ships as source files you own, not a compiled package. Copy the component files into your project under src/components/ui/:

src/
  components/
    ui/
      button.tsx
      card.tsx
      input.tsx
      label.tsx
      ...
  lib/
    utils.ts          # cn() helper
    theme-provider.tsx

Tip: use the build scripts

The scripts/build-tiers.js script automatically copies the right components for each tier into dist/. Run npm run build:tiers to generate distributable packages for all four tiers.

04Add the cn() utility

All components use a cn() helper to merge Tailwind classes. Add it to src/lib/utils.ts:

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

05Wrap your layout with ThemeProvider

Add ThemeProvider to your root layout so dark mode and theme context work throughout the app:

// src/app/layout.tsx
import { ThemeProvider } from "@/lib/theme-provider"

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

06Verify your installation

Import a component and render it to confirm everything is wired up correctly:

// src/app/page.tsx
import { Button } from "@/components/ui/button"

export default function HomePage() {
  return (
    <main className="flex min-h-screen items-center justify-center">
      <Button>Hello .skin!</Button>
    </main>
  )
}

// Run the dev server
npm run dev

If the button renders correctly with styles, you're all set.

Troubleshooting

Styles not applying

Make sure your Tailwind config's content glob includes ./src/components/**/*.tsx so Tailwind scans the component files.

useTheme must be used within ThemeProvider

This error means ThemeProvider is missing from your root layout, or you're rendering a component outside of it. Ensure it wraps your entire app in layout.tsx.

Module not found errors

Check that all Radix UI peer dependencies for your chosen tier are installed. Each tier has different dependencies — refer to the scripts/tier-mapping.js file for the complete list.

Next steps

Browse componentsLearn about themingGetting started overview