Capítulo 2 de 108

shadcn (CLI)

Core Idea

The shadcn CLI is the distribution mechanism: it initializes a project, adds components/dependencies, applies presets, inspects the registry, builds custom registries, and runs codemod-style migrations (icons, base color, RTL, radix imports).

Key Concepts

  • init: Initializes config/deps for a project (or creates one with --name); installs cn util and CSS variables.
  • add: Adds one or more components (name, url, or local path) to the project.
  • apply: Applies a preset code to an existing project; --only theme|font limits scope.
  • preset: Subcommands decode, resolve/info, url, open to inspect/resolve preset codes.
  • view / search (list): view previews registry items before installing; search/list queries registries (prefixed with @).
  • build: Reads registry.json and generates registry JSON files (default ./public/r) for custom/self-hosted registries.
  • docs: Fetches documentation/API reference for a component, optionally for a specific --base (base, radix, aria).
  • migrate: Runs codemods: icons, base-color, rtl, radix.
  • eject: Inlines shadcn/tailwind.css into your global CSS and removes the shadcn dependency (irreversible).

Code Examples

npx shadcn@latest init
npx shadcn@latest add button card dialog
npx shadcn@latest add --all
npx shadcn@latest view @acme/auth @v0/dashboard
npx shadcn@latest search @shadcn -q "button"
npx shadcn@latest migrate icons --from lucide --to phosphor --yes
npx shadcn@latest migrate base-color --to zinc --yes
npx shadcn@latest migrate rtl "src/components/ui/**"
npx shadcn@latest migrate radix src/components/ui/dialog.tsx
npx shadcn@latest build --output ./public/registry
npx shadcn@latest eject
  • O que demonstra: fluxo típico de projeto: iniciar, adicionar componentes, e migrar entre ícones/cor base/RTL/radix-ui sem reescrever manualmente.

Reference Tables

MigrationDescription
iconsMigrate UI components to a different icon library (lucide, tabler, hugeicons, phosphor, remixicon, radix legacy).
base-colorMigrate theme to a different base color (neutral, zinc, stone, mauve, olive, mist, taupe).
radixMigrate individual @radix-ui/react-* imports to the unified radix-ui package.
rtlMigrate physical CSS to logical (ml-4→ms-4) and add rtl: variants.

init key options: -t/--template (next, vite, start, react-router, laravel, astro), -b/--base (base, radix, aria), -p/--preset, -d/--defaults (template=next, preset=nova), --css-variables/--no-css-variables, --monorepo, --rtl, --pointer, --reinstall.

add key options: -a/--all, -o/--overwrite, -p/--path, --dry-run, --diff, --view.

Anti-patterns

  • Running eject casually: it's irreversible; future CLI updates to shadcn/tailwind.css no longer apply automatically afterward.
  • Migrating icons/base-color without --from/--to in CI: non-interactive runs need these flags or the command will prompt and hang.
  • Scoped migrate runs (specific file/glob) expecting components.json to update: only full-directory runs update components.json's iconLibrary/baseColor.

Key Takeaways

  1. add and init are the two commands used day-to-day; the rest (migrate, build, docs, search, preset) are situational.
  2. Migrations are codemods over your own copied code, consistent with the "open code" model: nothing is hidden in a package to auto-update.
  3. eject removes the shadcn npm dependency entirely by inlining its shared Tailwind utilities, a one-way door.
  4. build is for authoring/self-hosting your own component registry, not for consuming shadcn's.

Connects To

  • components-json: init/add read and write this config file.
  • theming: migrate base-color and CSS variables relate directly to the theming system.
AnteriorIntroductionPróximocomponents.json