1# shadcn/ui Setup Guide
2 
3This guide walks you through setting up shadcn/ui in both new and existing projects.
4 
5## Prerequisites
6 
7Before you begin, ensure you have:
8- **Node.js 18+** installed
9- **React 18+** in your project
10- **Tailwind CSS 3.0+** configured
11- A package manager: npm, yarn, pnpm, or bun
12 
13## Quick Start (New Project)
14 
15### Option 1: npx shadcn create (Recommended)
16 
17The easiest way to start a new project with shadcn/ui is using the `create` command, which allows you to customize everything (framework, library, style, font, etc.).
18 
19```bash
20npx shadcn@latest create
21```
22 
23This interactive command will guide you through:
241.  **Project Name**: Directory for your app.
252.  **Visual Style**: Choose from Vega, Nova, Maia, Lyra, Mira, or Classic.
263.  **Base Color**: Select your primary theme color.
274.  **Framework**: Next.js, Vite, Laravel, etc.
285.  **Component Library**: Choose **Radix UI** or **Base UI**.
296.  **RTL Support**: Enable Right-to-Left support if needed.
30 
31### Option 2: Classic Manual Setup (Next.js)
32 
33```bash
34# Create a new Next.js project
35npx create-next-app@latest my-app
36cd my-app
37 
38# Initialize shadcn/ui
39npx shadcn@latest init
40 
41# Add your first component
42npx shadcn@latest add button
43```
44 
45### Option 3: Classic Manual Setup (Vite + React)
46 
47```bash
48# Create a new Vite project
49npm create vite@latest my-app -- --template react-ts
50cd my-app
51npm install
52 
53# Install Tailwind CSS
54npm install -D tailwindcss postcss autoprefixer
55npx tailwindcss init -p
56 
57# Initialize shadcn/ui
58npx shadcn@latest init
59 
60# Add your first component
61npx shadcn@latest add button
62```
63 
64## Existing Project Setup
65 
66### Step 1: Ensure Tailwind CSS is Installed
67 
68If Tailwind is not installed:
69 
70```bash
71npm install -D tailwindcss postcss autoprefixer
72npx tailwindcss init -p
73```
74 
75Configure `tailwind.config.js`:
76 
77```javascript
78/** @type {import('tailwindcss').Config} */
79export default {
80  content: [
81    "./index.html",
82    "./src/**/*.{js,ts,jsx,tsx}",
83  ],
84  theme: {
85    extend: {},
86  },
87  plugins: [],
88}
89```
90 
91### Step 2: Initialize shadcn/ui
92 
93Run the initialization command:
94 
95```bash
96npx shadcn@latest init
97```
98 
99You'll be asked to configure:
100 
1011. **Style**: Choose between `default`, `new-york`, or one of the new styles (Vega, Nova, etc.)
102   - `default`: Clean and minimal design
103   - `new-york`: More refined with subtle details
104 
1052. **Base Color**: Choose your primary color palette
106   - slate, gray, zinc, neutral, or stone
107 
1083. **CSS Variables**: Recommend `yes` for easier theming
109 
1104. **TypeScript**: Recommend `yes` for type safety
111 
1125. **Import Alias**: Default is `@/components` (recommended)
113 
1146. **React Server Components**: Choose based on your framework
115   - `yes` for Next.js 13+ with app directory
116   - `no` for Vite, CRA, or Next.js pages directory
117 
1187. **RTL Support**: Answer `yes` if you need Right-to-Left layout support (this will use logical properties like `ms-4` instead of `ml-4`).
119 
120## Advanced Features
121 
122### Visual Styles
123shadcn/ui now offers multiple visual styles beyond the defaults:
124- **Vega**: The classic shadcn/ui look.
125- **Nova**: Reduced padding/margins, compact.
126- **Maia**: Soft, rounded, generous spacing.
127- **Lyra**: Boxy, sharp, mono font friendly.
128- **Mira**: Dense, compact.
129 
130### Base UI Support
131You can now choose between **Radix UI** and **Base UI** as the underlying primitive library. They share the same component API/abstraction, so your usage remains consistent.
132 
133 
134### Step 3: Verify Configuration
135 
136The init command creates/updates several files:
137 
138**components.json** (root of project):
139```json
140{
141  "$schema": "https://ui.shadcn.com/schema.json",
142  "style": "default",
143  "rsc": false,
144  "tsx": true,
145  "tailwind": {
146    "config": "tailwind.config.js",
147    "css": "src/index.css",
148    "baseColor": "slate",
149    "cssVariables": true
150  },
151  "aliases": {
152    "components": "@/components",
153    "utils": "@/lib"
154  }
155}
156```
157 
158**src/lib/utils.ts**:
159```typescript
160import { clsx, type ClassValue } from "clsx"
161import { twMerge } from "tailwind-merge"
162 
163export function cn(...inputs: ClassValue[]) {
164  return twMerge(clsx(inputs))
165}
166```
167 
168**Updated tailwind.config.js**:
169```javascript
170/** @type {import('tailwindcss').Config} */
171module.exports = {
172  darkMode: ["class"],
173  content: [
174    './pages/**/*.{ts,tsx}',
175    './components/**/*.{ts,tsx}',
176    './app/**/*.{ts,tsx}',
177    './src/**/*.{ts,tsx}',
178  ],
179  theme: {
180    container: {
181      center: true,
182      padding: "2rem",
183      screens: {
184        "2xl": "1400px",
185      },
186    },
187    extend: {
188      colors: {
189        border: "hsl(var(--border))",
190        input: "hsl(var(--input))",
191        ring: "hsl(var(--ring))",
192        background: "hsl(var(--background))",
193        foreground: "hsl(var(--foreground))",
194        primary: {
195          DEFAULT: "hsl(var(--primary))",
196          foreground: "hsl(var(--primary-foreground))",
197        },
198        // ... more colors
199      },
200      borderRadius: {
201        lg: "var(--radius)",
202        md: "calc(var(--radius) - 2px)",
203        sm: "calc(var(--radius) - 4px)",
204      },
205      keyframes: {
206        "accordion-down": {
207          from: { height: 0 },
208          to: { height: "var(--radix-accordion-content-height)" },
209        },
210        "accordion-up": {
211          from: { height: "var(--radix-accordion-content-height)" },
212          to: { height: 0 },
213        },
214      },
215      animation: {
216        "accordion-down": "accordion-down 0.2s ease-out",
217        "accordion-up": "accordion-up 0.2s ease-out",
218      },
219    },
220  },
221  plugins: [require("tailwindcss-animate")],
222}
223```
224 
225**Updated globals.css** (or equivalent):
226```css
227@tailwind base;
228@tailwind components;
229@tailwind utilities;
230 
231@layer base {
232  :root {
233    --background: 0 0% 100%;
234    --foreground: 222.2 84% 4.9%;
235    --card: 0 0% 100%;
236    --card-foreground: 222.2 84% 4.9%;
237    --popover: 0 0% 100%;
238    --popover-foreground: 222.2 84% 4.9%;
239    --primary: 221.2 83.2% 53.3%;
240    --primary-foreground: 210 40% 98%;
241    --secondary: 210 40% 96.1%;
242    --secondary-foreground: 222.2 47.4% 11.2%;
243    --muted: 210 40% 96.1%;
244    --muted-foreground: 215.4 16.3% 46.9%;
245    --accent: 210 40% 96.1%;
246    --accent-foreground: 222.2 47.4% 11.2%;
247    --destructive: 0 84.2% 60.2%;
248    --destructive-foreground: 210 40% 98%;
249    --border: 214.3 31.8% 91.4%;
250    --input: 214.3 31.8% 91.4%;
251    --ring: 221.2 83.2% 53.3%;
252    --radius: 0.5rem;
253  }
254 
255  .dark {
256    --background: 222.2 84% 4.9%;
257    --foreground: 210 40% 98%;
258    /* ... dark mode variables */
259  }
260}
261 
262@layer base {
263  * {
264    @apply border-border;
265  }
266  body {
267    @apply bg-background text-foreground;
268  }
269}
270```
271 
272### Step 4: Configure Path Aliases
273 
274Ensure your `tsconfig.json` includes path aliases:
275 
276```json
277{
278  "compilerOptions": {
279    "baseUrl": ".",
280    "paths": {
281      "@/*": ["./src/*"]
282    }
283  }
284}
285```
286 
287For Vite, also update `vite.config.ts`:
288 
289```typescript
290import path from "path"
291import { defineConfig } from "vite"
292import react from "@vitejs/plugin-react"
293 
294export default defineConfig({
295  plugins: [react()],
296  resolve: {
297    alias: {
298      "@": path.resolve(__dirname, "./src"),
299    },
300  },
301})
302```
303 
304### Step 5: Add Components
305 
306Now you can add components:
307 
308```bash
309# Add individual components
310npx shadcn@latest add button
311npx shadcn@latest add card
312npx shadcn@latest add dialog
313 
314# Add multiple components at once
315npx shadcn@latest add button card dialog input label
316```
317 
318Components will be added to `src/components/ui/` by default.
319 
320## Framework-Specific Considerations
321 
322### Next.js App Router
323 
324- Set `rsc: true` in `components.json`
325- Add `"use client"` to stateful components
326- Import components work from server components by default
327 
328### Next.js Pages Router
329 
330- Set `rsc: false` in `components.json`
331- All components are client-side by default
332 
333### Vite
334 
335- Ensure path aliases are configured in `vite.config.ts`
336- Import `globals.css` in your main entry point (`main.tsx`)
337 
338### Create React App
339 
340- Use `craco` or `react-app-rewired` for path alias support
341- Or use relative imports instead of aliases
342 
343## Verification Steps
344 
3451. **Check file structure**:
346   ```
347   src/
348   ├── components/
349   │   └── ui/
350   ├── lib/
351   │   └── utils.ts
352   └── index.css (or globals.css)
353   ```
354 
3552. **Test a simple component**:
356   ```tsx
357   import { Button } from "@/components/ui/button"
358   
359   export default function App() {
360     return <Button>Click me</Button>
361   }
362   ```
363 
3643. **Verify Tailwind is working**:
365   - Component should render with proper styling
366   - Check browser dev tools for applied classes
367 
3684. **Test dark mode** (if using CSS variables):
369   ```tsx
370   <html className="dark">
371   ```
372 
373## Troubleshooting
374 
375### "Cannot find module '@/components/ui/button'"
376 
377**Solution**: Check path alias configuration in `tsconfig.json` and framework config.
378 
379### Styles not applying
380 
381**Solution**: 
382- Ensure `globals.css` is imported in your app entry point
383- Verify Tailwind config `content` paths include your files
384- Check CSS variables are defined in `globals.css`
385 
386### TypeScript errors in components
387 
388**Solution**:
389- Run `npm install` to ensure all dependencies are installed
390- Check that `@types/react` is installed
391- Restart TypeScript server in your editor
392 
393### Components look broken
394 
395**Solution**:
396- Verify `tailwindcss-animate` is installed: `npm install tailwindcss-animate`
397- Check that CSS variables are properly defined
398- Ensure you're not overriding component styles globally
399 
400## Next Steps
401 
4021. Browse the [component catalog](./component-catalog.md)
4032. Read the [customization guide](./customization-guide.md)
4043. Check out example implementations in `/examples`
4054. Join the [shadcn/ui Discord](https://discord.com/invite/vNvTqVaWm6)
406 
407## Additional Resources
408 
409- [Official Documentation](https://ui.shadcn.com)
410- [Component Examples](https://ui.shadcn.com/examples)
411- [GitHub Repository](https://github.com/shadcn-ui/ui)
412- [Tailwind CSS Docs](https://tailwindcss.com/docs)
413