shadcn-vue（shadcn/ui Vue 命令行）

shadcn-vue

Quick Start (3 Minutes)

For Vue Projects (Vite)

1. Initialize shadcn-vue

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

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

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:

1. 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"

1. 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

1. 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"

1. 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)

1. 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"

1. 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

1. 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"

1. 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.