ShadCN UI Component Installation Skill

Quick Reference

When to use this skill:

• •Installing ShadCN UI components
• •Fixing ShadCN import errors
• •Setting up new UI components

CRITICAL Version Lock

ONLY USE: ShadCN v2.3.0

Why: Newer versions require Tailwind v4, which is incompatible with Wasp.

Complete Installation Workflow

Step 1: Install Component

npx shadcn@2.3.0 add button
# Replace 'button' with desired component name

CRITICAL: Always use @2.3.0 version lock

Step 2: Fix Import Path (MANDATORY)

This fix is REQUIRED for EVERY component installation!

File location: app/src/client/components/ui/{component}.tsx

Before (WRONG):

import { cn } from "s/lib/utils";

After (CORRECT):

import { cn } from "../../lib/utils";

Why: ShadCN generates wrong import path. Must fix manually.

Step 3: Use Component

import { Button } from '@/components/ui/button'

<Button variant="default">Click me</Button>

Available Components

Common components to install:

• •button
• •card
• •dialog
• •dropdown-menu
• •input
• •label
• •textarea
• •select
• •checkbox
• •radio-group
• •switch
• •accordion
• •tabs
• •toast
• •alert
• •badge
• •form
• •table
• •sheet

Component Location

All ShadCN components go in:

app/src/client/components/ui/
├── button.tsx
├── card.tsx
├── dialog.tsx
└── ...

Common Errors & Solutions

Error: Cannot find module 's/lib/utils'

Cause: Forgot to fix import path after installation

Fix: Change import in component file:

-import { cn } from "s/lib/utils"
+import { cn } from "../../lib/utils"

Error: Component styling broken

Cause: Wrong import path or missing Tailwind config

Fix:

1. •Verify import path fix was applied
2. •Check tailwind.config.js has ShadCN config

Error: ShadCN version mismatch

Cause: Used wrong version (not v2.3.0)

Fix: Uninstall and reinstall with correct version:

rm app/src/client/components/ui/{component}.tsx
npx shadcn@2.3.0 add {component}

Installation Checklist

After EVERY component installation:

• • Used npx shadcn@2.3.0 add {component}
• • Fixed import path from s/lib/utils to ../../lib/utils
• • Verified component renders correctly
• • No import errors in console

Critical Rules

✅ DO:

• •Always use @2.3.0 version lock
• •Fix import path after every installation
• •Verify component works before proceeding

❌ NEVER:

• •Use shadcn without version lock
• •Skip import path fix
• •Use newer ShadCN versions (breaks with Tailwind v4)

Examples

Installing Button Component

# 1. Install
npx shadcn@2.3.0 add button

# 2. Fix import in app/src/client/components/ui/button.tsx
# Change: import { cn } from "s/lib/utils"
# To: import { cn } from "../../lib/utils"

# 3. Use
import { Button } from '@/components/ui/button'
<Button>Click me</Button>

Installing Multiple Components

npx shadcn@2.3.0 add button card dialog

# Then fix import path in ALL THREE files:
# - app/src/client/components/ui/button.tsx
# - app/src/client/components/ui/card.tsx
# - app/src/client/components/ui/dialog.tsx

Troubleshooting

If components don't work after installation:

1. •Check version: npm list shadcn-ui
2. •Verify import path fix was applied
3. •Check Tailwind config includes ShadCN
4. •Restart wasp: ../scripts/safe-start.sh (multi-worktree safe)