shadcn-vue

What this skill does

# shadcn-vue Production Stack

**Production-tested**: Vue/Nuxt applications with accessible, customizable components
**Last Updated**: 2025-12-09
**Status**: Production Ready ✅
**Latest Version**: shadcn-vue@latest (Reka UI v2)
**Dependencies**: Tailwind CSS, Reka UI, Vue 3+ or Nuxt 3+

---

## Quick Start (3 Minutes)

### For Vue Projects (Vite)

#### 1. Initialize shadcn-vue

```bash
# Using Bun (recommended)
bunx shadcn-vue@latest init

# Using npm
npx shadcn-vue@latest init
```

**During initialization**:
- Style: `New York` or `Default` (cannot change later!)
- Base color: `Slate` (recommended)
- CSS variables: `Yes` (required for dark mode)

#### 2. Configure TypeScript Path Aliases

```json
// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

#### 3. Configure Vite

```typescript
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import tailwindcss from '@tailwindcss/vite' // Tailwind v4
import path from 'path'

export default defineConfig({
  plugins: [vue(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})
```

#### 4. Add Your First Component

```bash
bunx shadcn-vue@latest add button
# or: npx shadcn-vue@latest add button
```

**See Full Setup**: `templates/quick-setup.ts`

---

### For Nuxt Projects

```bash
# Create project with Tailwind
bun create nuxt-app my-app
cd my-app
bun add -D @nuxtjs/tailwindcss

# Configure Nuxt
# nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/tailwindcss']
})

# Initialize shadcn-vue
bunx shadcn-vue@latest init
# or: npx shadcn-vue@latest init
# or: pnpm dlx shadcn-vue@latest init
```

---

## Component Library (50+ Components)

### Navigation & Layout
- Accordion, Alert Dialog, Avatar, Badge, Breadcrumb, Card, Carousel, Collapsible, Dialog, Drawer, Dropdown Menu, Menu Bar, Navigation Menu, Pagination, Popover, Resizable, Scroll Area, Sheet, Sidebar, Tabs, Toast, Tooltip

### Form Components
- Auto Form, Button, Calendar, Checkbox, Combobox, Command, Context Menu, Date Picker, Form, Input, Input OTP, Label, Number Field, PIN Input, Radio Group, Range Calendar, Select, Slider, Sonner, Switch, Textarea, Toggle, Toggle Group

### Data Display
- Aspect Ratio, Data Table, Skeleton, Stepper, Splitter, Table, Tag Input

### Advanced
- Charts (Unovis), Color Picker, Editable, File Upload, Sortable

**Full Component Reference**: https://shadcn-vue.com/docs/components

---

## Auto Form - Schema-Based Forms

### Installation

```bash
bunx shadcn-vue@latest add auto-form
# or: npx shadcn-vue@latest add auto-form

bun add zod
# or: npm install zod
```

### Basic Usage

```vue
<script setup lang="ts">
import { AutoForm } from '@/components/ui/auto-form'
import { z } from 'zod'

const schema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters'),
  email: z.string().email('Invalid email'),
  age: z.number().min(18, 'Must be 18 or older'),
  bio: z.string().optional(),
  subscribe: z.boolean().default(false)
})

function onSubmit(values: z.infer<typeof schema>) {
  console.log('Form submitted:', values)
}
</script>

<template>
  <AutoForm :schema="schema" @submit="onSubmit">
    <template #submit>
      <Button type="submit">Submit</Button>
    </template>
  </AutoForm>
</template>
```

**Supported Field Types**: string, number, boolean, date, enum, array, object

---

## Data Tables with TanStack Table

### Installation

```bash
bunx shadcn-vue@latest add data-table
# or: npx shadcn-vue@latest add data-table

bun add @tanstack/vue-table
# or: npm install @tanstack/vue-table
```

### Basic Setup

```vue
<script setup lang="ts">
import { DataTable } from '@/components/ui/data-table'
import { h } from 'vue'

const columns = [
  {
    accessorKey: 'id',
    header: 'ID',
  },
  {
    accessorKey: 'name',
    header: 'Name',
  },
  {
    accessorKey: 'email',
    header: 'Email',
  }
]

const data = [
  { id: 1, name: 'John Doe', email: '[email protected]' },
  { id: 2, name: 'Jane Smith', email: '[email protected]' }
]
</script>

<template>
  <DataTable :columns="columns" :data="data" />
</template>
```

**Features**: Sorting, filtering, pagination, row selection, column visibility, expandable rows

---

## Dark Mode Implementation

### Installation

```bash
bun add @vueuse/core
# or: npm install @vueuse/core
```

### Setup Theme Provider

```vue
<!-- components/ThemeProvider.vue -->
<script setup lang="ts">
import { useColorMode } from '@vueuse/core'

const mode = useColorMode()
</script>

<template>
  <div :class="mode">
    <slot />
  </div>
</template>
```

### Use in Components

```vue
<script setup>
import { useColorMode } from '@vueuse/core'

const mode = useColorMode()

function toggleTheme() {
  mode.value = mode.value === 'dark' ? 'light' : 'dark'
}
</script>

<template>
  <Button @click="toggleTheme">
    {{ mode === 'dark' ? '🌙' : '☀️' }}
  </Button>
</template>
```

---

## Critical Rules

### Always Do

✅ **Run `init` before adding components**
- Creates required configuration and utilities
- Sets up path aliases

✅ **Use CSS variables for theming** (`cssVariables: true`)
- Enables dark mode support
- Flexible theme customization

✅ **Configure TypeScript path aliases**
- Required for component imports
- Must match `components.json` aliases

✅ **Keep components.json in version control**
- Team members need same configuration
- Documents project setup

✅ **Use Bun for faster installs** (recommended)
- 10-20x faster than npm

### Never Do

❌ **Don't change `style` after initialization**
- Requires complete reinstall
- Reinitialize in new directory instead

❌ **Don't mix Radix Vue and Reka UI v2**
- Incompatible component APIs
- Use one or the other

❌ **Don't skip TypeScript configuration**
- Component imports will fail
- IDE autocomplete won't work

❌ **Don't use without Tailwind CSS**
- Components are styled with Tailwind
- Won't render correctly

---

## Top 7 Critical Issues

### Issue #1: Missing TypeScript Path Aliases

**Error**: `Cannot find module '@/components/ui/button'`

**Solution**:
```json
// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

---

### Issue #2: Tailwind CSS Not Configured

**Error**: Components render without styles

**Solution**:
```css
/* src/assets/index.css */
@import "tailwindcss";
```

```typescript
// vite.config.ts (Tailwind v4)
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [vue(), tailwindcss()]
})
```

---

### Issue #3: CSS Variables Not Defined

**Error**: Theme colors not applying, gray/transparent components

**Solution**: Ensure all CSS variables are defined (run `init` command)

---

### Issue #4: Wrong Style Selected

**Error**: Components look different than expected

**Solution**: Choose carefully during `init` (New York or Default) - cannot change later without reinstall

---

### Issue #5: Mixing Radix Vue and Reka UI

**Error**: Type conflicts, duplicate components

**Solution**:
- Use `bunx shadcn-vue@latest` for Reka UI v2
- Use `bunx shadcn-vue@radix` for legacy Radix Vue
- Don't mix both

---

### Issue #6: Monorepo Path Issues

**Error**: Components installed in wrong directory

**Solution**: Use `-c` flag to specify workspace:
```bash
bunx shadcn-vue@latest init -c ./apps/web
bunx shadcn-vue@latest add button -c ./apps/web
```

---

### Issue #7: Component Import Fails After Manual Edit

**Error**: Import paths broken after editing `components.json`

**Solution**: Keep `components.json` and `tsconfig.json` aliases in sync. Test imports after any config changes.

---

**See All 7 Issues**: `references/error-catalog.md`

---

## CLI Commands Reference

### init Command

```bash
# Initialize in current directory
bunx shadcn-vue@latest init
# or: npx shadcn-vue@latest init

# Initialize in specific directory (monorepo)
bunx shadcn-vue@latest init -c ./apps/web