shadcn-ui
ShadCN UI component installation workflow for Wasp projects. Use when installing ShadCN components, fixing import errors, or working with UI components. Includes CRITICAL version lock (v2.3.0 ONLY) and mandatory import path fix.
When & Why to Use This Skill
This Claude skill streamlines the ShadCN UI component installation workflow specifically for Wasp projects. It addresses critical compatibility issues by enforcing a version lock on ShadCN v2.3.0 (ensuring Tailwind v3 compatibility) and automatically correcting the common 's/lib/utils' import path error. By automating these manual fixes, it ensures a stable and error-free UI development environment for Wasp developers.
Use Cases
- Seamlessly installing and configuring ShadCN UI components like Buttons, Dialogs, and Cards within a Wasp framework project structure.
- Automatically resolving 'Cannot find module s/lib/utils' errors by fixing the incorrect import paths generated by the standard ShadCN CLI.
- Ensuring project stability by strictly maintaining ShadCN v2.3.0 to prevent breaking changes associated with Tailwind v4 in newer ShadCN versions.
- Standardizing UI component locations and installation patterns across a development team working on Wasp-based applications.
| name | shadcn-ui |
|---|---|
| description | ShadCN UI component installation workflow for Wasp projects. Use when installing ShadCN components, fixing import errors, or working with UI components. Includes CRITICAL version lock (v2.3.0 ONLY) and mandatory import path fix. |
| version | 1.0 |
| last_updated | 2025-10-18 |
| allowed_tools | [Bash, Edit, Read] |
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/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/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.jshas ShadCN config
Error: ShadCN version mismatch
Cause: Used wrong version (not v2.3.0)
Fix: Uninstall and reinstall with correct version:
rm app/src/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/utilsto../../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/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/components/ui/button.tsx
# - app/src/components/ui/card.tsx
# - app/src/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)