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:

Verify import path fix was applied
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:

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

shadcn-ui