2. Configure TypeScript Path Aliases

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

3. Configure Vite

// 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

npx shadcn-vue@latest add button

Quick Reference

Need	Command or file
Initialize project	`npx shadcn-vue@latest init`
Add component	`npx shadcn-vue@latest add button`
Add multiple components	`npx shadcn-vue@latest add button card dialog`
Build registry JSON	`npx shadcn-vue@latest build`
Generate component docs	`npx tsx scripts/generate-shadcn-components.ts`
Enable CSS variables	`components.json` → `tailwind.cssVariables: true`
Add registry namespace	`components.json` → `registries` map
Opencode MCP init	`npx shadcn-vue@latest mcp init --client opencode`
Codex MCP config	`~/.codex/config.toml` with `mcp_servers.shadcn`

Bundled Resources

Templates (templates/):

quick-setup.ts - Complete setup guide for Vue/Nuxt with examples (190 lines)

References (references/):

cli.md - CLI commands and options
mcp.md - MCP setup, client configs, prompts
theming.md - Theming and cssVariables
error-catalog.md - All 7 documented issues with solutions (267 lines)
component-examples.md - All 50+ component examples with code
dark-mode-setup.md - Complete dark mode implementation guide
data-tables.md - Data tables with TanStack Table

Component Documentation (components/):

references/components.md - Index of all shadcn-vue components
components/<component>.md - Individual component documentation with installation, usage, and examples

Official Documentation:

shadcn-vue Docs: https://shadcn-vue.com
Reka UI Docs: https://reka-ui.com
GitHub: https://github.com/radix-vue/shadcn-vue

When to Load References

Load these references based on the task:

Load references/error-catalog.md when:
- User encounters "component not found" or import errors
- Setup commands fail or configuration issues arise
- Tailwind CSS variables or TypeScript paths broken
- Trigger phrases: "not working", "error", "fails to", "broken"
Load references/components.md when:
- User asks what components are available (names, categories, status)
- User needs to add/use a component and wants the correct install/import paths
- You need to confirm a component exists before recommending a custom build
Load references/component-examples.md when:
- User asks "how do I implement [component]?"
- Need copy-paste examples for specific components
- Building forms, tables, navigation, or data display
- Trigger phrases: "example", "how to use", "implement", "code sample"
Load references/cli.md when:
- User asks how to run the CLI (init, add, update) or what prompts mean
- Need the exact command/flags for installing one or more components
- Troubleshooting CLI-related issues (registry, paths, overwrites)
Load references/dark-mode-setup.md when:
- Implementing dark mode / theme switching
- User mentions Vue 3 + Vite, Nuxt, or Astro setup
- Need composable patterns for theme management
- Trigger phrases: "dark mode", "theme", "light/dark", "color scheme"
Load references/theming.md when:
- User wants to customize theme tokens via CSS variables (cssVariables, :root, .dark)
- Need to wire Tailwind to CSS-variable-based colors and radii
- Setting up/adjusting design tokens (colors, radius, typography) for shadcn-vue
Load references/mcp.md when:
- Setting up MCP server for opencode, Codex, Cursor, VS Code
- Configuring registries in components.json
- Troubleshooting missing components or registry namespaces
- Trigger phrases: "MCP", "opencode", "codex", "cursor", "registry"
Load references/data-tables.md when:
- Building sortable/filterable/paginated tables
- User mentions TanStack Table or DataTable
- Trigger phrases: "data table", "table", "tanstack", "sorting", "pagination"

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

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

Common Mistakes

Running add before init and missing components.json.
Forgetting to enable the MCP server in the client UI/config.
Mis-typed registry namespaces (@namespace/component).
Using CSS variable classes without tailwind.cssVariables: true.

CLI Commands Reference

init Command

# Initialize in current directory
npx shadcn-vue@latest init

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

add Command

# Add single component
npx shadcn-vue@latest add button

# Add multiple components
npx shadcn-vue@latest add button card dialog

# Add all components
npx shadcn-vue@latest add --all

diff Command

# Check for component updates
npx shadcn-vue@latest diff button

mcp Command

# Initialize MCP for specific client
npx shadcn-vue@latest mcp init --client opencode
npx shadcn-vue@latest mcp init --client codex
npx shadcn-vue@latest mcp init --client cursor
npx shadcn-vue@latest mcp init --client vscode

Configuration

shadcn-vue uses components.json to configure:

Component paths (@/components/ui)
Utils location (@/lib/utils)
Tailwind config paths
TypeScript paths

Full example: See templates/components.json or generate via npx shadcn-vue@latest init

Utils Library

The @/lib/utils.ts file provides the cn() helper for merging Tailwind classes:

Combines multiple className strings
Uses clsx + tailwind-merge for conflict resolution

Auto-generated by shadcn-vue init - no manual setup needed.

shadcn-vue

shadcn-vue

Quick Start (3 Minutes)

For Vue Projects (Vite)

1. Initialize shadcn-vue