Must always be enabled when working with shadcn-ui.
shadcn-ui is NOT an npm package. It's a code distribution platform that copies component source code directly into your project.
Key principle: Components are added via CLI (pnpx shadcn@latest add) from a remote registry, NOT installed as dependencies.
# Add single component
pnpx shadcn@latest add button
# Add multiple components
pnpx shadcn@latest add button card dialog
# Add all components
pnpx shadcn@latest add --all
# Preview component before adding
pnpx shadcn@latest view button
Important: Always use the CLI to add components. Do NOT create component files manually in components/ui/ unless explicitly instructed.
pnpx shadcn@latest view <component-name> to preview before adding# Add from namespaced registry
pnpx shadcn@latest add @v0/dashboard
# Add from URL
pnpx shadcn@latest add https://example.com/r/custom-component.json
Registry configuration is in components.json:
{
"registries": {
"@acme": "https://registry.acme.com/r/{name}.json"
}
}
NEVER directly edit files in these directories without explicit user instruction:
components/ui/ - CLI-generated component filescomponents.json aliasesWhy?: These files are managed by the CLI. Direct edits will be lost on updates.
Step 1: Try usage-side control first
// ✅ Best: Control via props/className/composition at usage site
<Button className="custom-styling" onClick={customHandler} />
Step 2: If usage-side control is insufficient
You MUST ask the user for permission before modifying components/ui/ files.
Required information for user approval:
Example request:
The Button component needs to support an
iconprop for consistent icon positioning. This cannot be achieved via className alone because it requires conditional rendering logic. I propose adding an optionalicon?: React.ReactNodeprop and rendering it with fixed spacing before children. May I modifycomponents/ui/button.tsx?
Only proceed with modification after receiving explicit user approval.
For comprehensive reference when documentation is insufficient, consult: https://ui.shadcn.com/llms.txt
components.json at project rootpnpx shadcn@latest add <component> --overwrite to updateRemember: shadcn-ui provides the code, not the package. You maintain full control and ownership.
