shadcn-setup

Shadcn Setup

Use this skill to add Shadcn UI to a project that already exists but doesn't have it configured.

Documentation

• Shadcn Installation

Workflow

1. Environment & Prerequisites Detection

Before initializing, ensure the environment is ready:

A. Framework

• Next.js: check for next.config.js or next.config.ts.
• Vite: check for vite.config.ts or vite.config.js.

B. Tailwind CSS (CRITICAL)

Shadcn requires Tailwind CSS. Verify it is installed and configured:

• Check for tailwind.config.js / tailwind.config.ts (v3).
• OR check for specific Tailwind v4 CSS imports in globals.css/index.css.
• If missing: Install Tailwind CSS first (follow official Tailwind guides for the specific framework). DO NOT proceed with shadcn init without Tailwind.

C. Path Aliases (tsconfig.json)

Shadcn relies on path aliases (e.g., @/lib/utils).

• Read tsconfig.json (or jsconfig.json).
• Ensure "paths": { "@/*": ["./src/*"] } (or similar) is configured.
• If missing: Add the alias configuration to compilerOptions.

2. Initialization

Run the init command using pnpm:

pnpm dlx shadcn@latest init

3. Configuration

Follow these defaults unless specified otherwise:

• Style: New York (Default) or Default.
• Base Color: Slate.
• CSS Variables: YES (Critical for dynamic theming).
• Aliasing: Accept defaults (usually @/components, @/lib/utils) or match tsconfig.json.

4. Cleanup & Boilerplate Removal

For Next.js (app/)

1. Clean page.tsx: Replace default Next.js hero content with a simple shadcn Button to verify setup.
2. Clean globals.css: Remove all default styling (root variables for foreground/background-rgb) EXCEPT:
   • Tailwind directives (@tailwind base;...)
   • Shadcn layer definitions (@layer base { ... })

For Vite (src/)

1. Clean App.tsx: Remove logos, count state, and default boilerplates. Replace with a simple shadcn content.
2. Clean index.css: Ensure it contains Tailwind directives and Shadcn base layers. Remove legacy :root styles if they conflict.

5. Verification

• Check components.json exists.
• Check lib/utils.ts (or configured alias) exists and exports cn.

References

• Troubleshooting Common Errors