shadcn/ui Setup
What the setup command does, where files go, and how to add components to your project
Why First — The Scenario
You're preparing client reports and you need a standard format: company logo top-right, client name, date, table of figures, signature block at the bottom. You could format each one from scratch — or you could create one template and use it for every client. One change to the template updates all future reports instantly.
shadcn/ui is your UI template library. Every button, input field, card, dialog, and data table is pre-built and pre-formatted. You grab what you need, place it in your project, and customise from there. Professional results from the first line of code.
What shadcn/ui Actually Does
Most people misunderstand what shadcn/ui is. It is not a package you install from npm in the traditional sense. Here's what actually happens:
When you run the add command, shadcn/ui:
- Downloads the component source code
- Creates the file in your
src/components/ui/folder - Installs any required npm packages the component depends on
- Does nothing else
The component file is now yours. It's sitting in your project, in your Git repository, editable by you. There is no shadcn/ui runtime, no black box, no version lock-in. You can read every line of the button component. You can change whatever you want.
This is different from most libraries. Material UI, Chakra UI, and Ant Design give you components you import from their npm package. You can't easily modify them. shadcn/ui gives you the source code. You own it.
The Setup Command (Already Done For You)
When starting a fresh project, the one-time setup command is:
This is already done in every project created with the Sahinov training stack. You will not run this command during training. Understanding what it does helps you read the resulting files.
What It Asks During Init
The command runs an interactive setup. Here's what it asks and what to answer for Sahinov projects:
| Question | Answer | Why |
|---|---|---|
| Which style would you like to use? | Default | Standard shadcn look, easy to customise |
| Which color would you like to use as base color? | Slate | Clean gray base, works with any accent color |
| Where is your global CSS file? | src/index.css | Where Tailwind is imported |
| Would you like to use CSS variables for colors? | Yes | Enables the theming system |
| Are you using React Server Components? | No (for Vite projects) | We use Vite, not Next.js |
Where is your tailwind.config.ts? | tailwind.config.ts | Default location |
| Configure the import alias for components? | @/components | Matches our folder structure |
What It Creates
After init, these files are created or modified:
The components.json File
This file tells the shadcn CLI where to put things:
You will never need to edit this file manually. The CLI reads it when you run add commands.
The cn() Helper Function
Every shadcn component uses a small utility function called cn. It's created at src/lib/utils.ts:
This function merges Tailwind classes intelligently. Without it, if you tried to override a class — for example changing a component's padding — both your padding and the original padding would apply and conflict. cn() resolves the conflict automatically, keeping only the last relevant class.
You will use cn() whenever you need to apply conditional or custom classes:
Adding Components
Once the project is initialised, adding components is a single command:
This creates src/components/ui/button.tsx in your project.
Common First Components to Add
Add these when starting a new project — they cover most of your UI needs:
Button — The most-used component. Multiple variants built in.
Input — Styled text input with consistent focus states.
Card — Container with header, content, and footer sections.
Form — Form wrapper that integrates with React Hook Form.
Dialog — Modal overlay with backdrop and close button.
Select — Dropdown selector with keyboard support.
Table — Structured table with header and rows.
Badge — Small label for status and categories.
You can also add multiple components at once:
Where the Files Go
Every added component lands in src/components/ui/:
Your own custom components go in src/components/ (not inside ui/). Keep shadcn components in ui/ and your own components outside of it.
Importing Components
Once a component is added, import it from its file:
The @/ prefix is a path alias meaning src/. So @/components/ui/button is the same as src/components/ui/button. This alias is set up in your project's TypeScript config and Vite config.
Checking the shadcn/ui Documentation
Every component has documentation at ui.shadcn.com. The docs show:
- Installation command
- How to import it
- Every variant and prop it supports
- Code examples you can copy directly
Claude Code also knows the shadcn/ui API well. You can ask:
"Add a shadcn Button with destructive variant and a trash icon from lucide-react"
and get the correct, working code immediately.
The pattern for every new component:
- Check ui.shadcn.com to see if it exists
- Run
npx shadcn-ui@latest add [name] - Import it and use it
- Customise with additional Tailwind classes as needed
You will use this pattern dozens of times across your projects.