How to install shadcn/ui in an existing project

Short answer: from the project root run npx shadcn@latest init, then add a component with npx shadcn@latest add button. You are not installing a package: the CLI copies TypeScript files into your repository.

What you need before running init

• A project with package.json and Tailwind CSS already configured: the 2026 guide assumes Tailwind CSS 4.
• An import alias such as @/* in tsconfig.json or jsconfig.json.
• The global CSS file where the theme tokens live.

If one of the three is missing, init still writes the files but the imports do not resolve. The usual error is Cannot find module '@/lib/utils', and the cause sits in the alias, not in the component.

# 1. inizializza configurazione, dipendenze e token
npx shadcn@latest init

# 2. aggiungi il primo componente
npx shadcn@latest add button

What init writes into the project

• components.json: aliases, CSS path, base colour and style.
• lib/utils.ts: the cn helper that merges classes.
• The theme CSS variables in the global file, plus the dependencies the component needs.

The command does not create an @shadcn/ui package: components land in components/ui and from then on they are your code. shadcn/ui is MIT licensed (repository), as are Tailwind CSS and Radix UI, the primitives the components build on.

A concrete example: components.json

The file that decides everything is components.json, written by init and read by every add. If the tailwind.css path points at a sheet that does not exist, the tokens never arrive and the components render without colour.

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

Read three keys and you know whether the project agrees with itself: aliases.ui decides where components land, tailwind.css where the tokens land, and tailwind.config stays empty on Tailwind CSS 4. If any of the three does not match the real folder, fix it before adding a second component.

The check that prevents most problems

npx shadcn@latest info
npx shadcn@latest add card --dry-run

info prints the configuration the CLI actually reads: if the CSS path or the alias differs from what you expect, stop here. --dry-run lists the files without writing them, so you see in advance whether the command wants to touch something you already edited.

Monorepos and nested folders

The CLI looks for components.json in the current folder and does not walk up the tree. In a monorepo, run the command from the workspace that holds the file, or pass -c with the path.

# dalla radice del repository
npx shadcn@latest add card -c apps/web

A named limitation

The cssVariables choice is made at init and lasts: to move from CSS tokens to inline utilities, the official docs tell you to delete and reinstall the components. Make that decision before you build ten screens, not after.

The decision rule

Rule: count the registryDependencies the block declares. Up to two, add is safe; past five, read the list and add the components one at a time so the diff stays readable. The catalogue maximum is twenty, and a single command would write all of them at once.

The mistake to avoid

Re-running add button on a component you already edited is the most expensive mistake: the CLI overwrites the file without asking and your changes vanish without a warning. Commit before every add; if the diff shows files you did not mean to touch, git checkout puts them back.

Where to continue

The EneUI catalogue starts from the shadcn library, with records such as the sidebar, and from 1,556 block previews. For the next step read how shadcn blocks work and private registries; for project structure, App Router in 2026. The theme comparison is free versus premium shadcn themes.