| name | shadcn-component-install |
| description | Install shadcn/ui components via CLI with mandatory dry-run preview before write. Workflow: info → search → docs → diff → install. |
| version | 1.0.0 |
| when | {"keywords":["shadcn","ui component","button","dialog","accordion","card","install component","shadcn-ui","radix","registry"]} |
| allowed-tools | ["Bash(npx shadcn@latest *)","Bash(pnpm dlx shadcn@latest *)","Bash(bunx shadcn@latest *)","Read","Grep","Glob"] |
shadcn-component-install — CLI-First Component Installation
Agent directive
Whenever the user asks to "add a button", "install a dialog", "scaffold an accordion" or any shadcn/ui component — DO NOT copy code from documentation into the project manually. Always use the shadcn CLI. The CLI resolves dependencies, applies registry config (style, baseColor, aliases), wires cn() and Tailwind tokens, and keeps components upgradeable.
If components.json is missing, run init first.
Hard rules
- NEVER paste component source from
ui.shadcn.com directly into the project.
- NEVER skip the
--dry-run step on a project that already has components installed (collisions silently overwrite files otherwise).
- NEVER pin to an old shadcn version unless the user explicitly asks — always use
shadcn@latest.
- ALWAYS detect the package manager before invoking (
pnpm-lock.yaml → pnpm dlx; bun.lockb → bunx; default → npx).
- ALWAYS read the existing
components.json before installing, so style/baseColor/aliases match.
Workflow (5 steps, all executable)
Step 1 — info: confirm project is shadcn-ready
npx shadcn@latest info
Reads components.json, prints framework, style, baseColor, iconLibrary, and resolved aliases. If the command fails with "components.json not found", run:
npx shadcn@latest init
and stop to confirm style + baseColor with the user before proceeding.
Step 2 — search: find the exact component slug
npx shadcn@latest search <query>
Example:
npx shadcn@latest search dialog
npx shadcn@latest search "data table"
Use the slug from the output (e.g. dialog, data-table) for the next steps. If the search returns multiple registries (e.g. @shadcn/dialog, @magicui/dialog), ask the user which one they want — do NOT guess.
Step 3 — view: read component docs and dependencies
npx shadcn@latest view <slug>
Example:
npx shadcn@latest view dialog
This prints the component's files, registryDependencies (other shadcn components it pulls in), and npm dependencies. Surface this to the user before writing — especially the npm deps, since they affect lockfile and bundle size.
Step 4 — --dry-run: preview the diff
npx shadcn@latest add <slug> --dry-run
Example:
npx shadcn@latest add dialog --dry-run
The CLI lists every file it would create or overwrite. If any line says OVERWRITE, STOP and ask the user — do not proceed unless they say "yes, overwrite".
For multiple components in one go:
npx shadcn@latest add dialog button label --dry-run
Step 5 — Install
Only after the dry-run is reviewed:
npx shadcn@latest add <slug>
If overwrites were approved, append --overwrite. If the user wants a specific path override, append --path src/components/ui.
After install, run the project's typecheck (e.g. pnpm tsc --noEmit) to confirm imports resolve. Do NOT skip this — registry mismatches surface as TS errors first.
Package manager detection
test -f pnpm-lock.yaml && echo "pnpm dlx shadcn@latest"
test -f bun.lockb && echo "bunx shadcn@latest"
test -f yarn.lock && echo "yarn dlx shadcn@latest"
echo "npx shadcn@latest"
Use the detected runner consistently across all 5 steps. Mixing runners triggers cache misses and slower installs.
Anti-patterns (refuse these)
| Anti-pattern | Why it breaks | Correct replacement |
|---|
Copy <Dialog> source from ui.shadcn.com into src/components/ui/dialog.tsx | Skips registryDependencies, breaks future diff upgrades, hardcodes wrong cn alias | npx shadcn@latest add dialog |
npx shadcn add dialog (no --dry-run first) | Silent overwrite of customized components | Run dry-run, review, then add |
npm install @radix-ui/react-dialog then write your own wrapper | Misses Tailwind tokens, animation classes, a11y wiring | Use the registry component as base, customize after |
Using shadcn-ui@0.x (deprecated) | Old CLI with broken registry resolution | shadcn@latest (no -ui suffix) |
| Pasting from a chat answer that includes the source | Same as #1, plus stale snapshots | Always add from CLI |
Reference: common slugs
button · dialog · dropdown-menu · form · input · label · select · sheet · table · tabs · toast · tooltip · accordion · alert · alert-dialog · avatar · badge · calendar · card · checkbox · command · data-table · date-picker · popover · progress · radio-group · scroll-area · separator · skeleton · slider · switch · textarea · toggle
When unsure, run search (Step 2) — never guess slugs.
Sources
