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)