components.json

Core Idea

components.json configures how the CLI generates components for your specific project (style, Tailwind setup, import aliases, registries). Only needed if using the CLI; the copy-paste method doesn't require it.

Key Concepts

• style: "new-york" (the default style is deprecated). Cannot be changed after init.
• tailwind.config: path to tailwind.config.js/ts; leave blank for Tailwind v4.
• tailwind.css: path to the CSS file importing Tailwind.
• tailwind.baseColor: one of neutral | stone | zinc | mauve | olive | mist | taupe; sets default theme tokens; immutable after init.
• tailwind.cssVariables: true generates semantic tokens (background, primary, ...); false generates inline Tailwind color utilities. Immutable after init (switching requires delete + reinstall).
• tailwind.prefix: prefix applied to all Tailwind utility classes the CLI adds.
• rsc: true auto-adds "use client" to client components (React Server Components support).
• tsx: false installs components as .jsx instead of .tsx.
• aliases: utils, components, ui, lib, hooks import roots, backed by tsconfig/jsconfig paths or package.json#imports.
• registries: named (@name) registry URL templates, optionally with headers/params for auth, used via npx shadcn add @name/item.

Code Examples

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "tailwind": {
    "css": "styles/global.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "rsc": true,
  "tsx": true,
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks",
    "utils": "@/lib/utils"
  },
  "registries": {
    "@private": {
      "url": "https://api.company.com/registry/{name}.json",
      "headers": { "Authorization": "Bearer ${REGISTRY_TOKEN}" }
    }
  }
}

• O que demonstra: config completa típica, incluindo registry privado autenticado via variável de ambiente ${VAR_NAME} (expandida automaticamente).

Anti-patterns

• Trying to change style, tailwind.baseColor, or tailwind.cssVariables post-init: these are locked in; switching cssVariables requires deleting and reinstalling components.
• Setting tailwind.config under Tailwind v4: leave it blank, it's a v3-era field.

Key Takeaways

1. components.json is the CLI's map of your project conventions, not runtime config shipped to the app.
2. Three fields are permanent decisions at init time: style, baseColor, cssVariables.
3. registries + namespaced add @name/item is how private/team component sources are wired in.
4. Environment variables inside registries.*.headers/params use ${VAR_NAME} syntax and expand from the shell environment.

Connects To

• cli: init/add read and write this file.
• theming: cssVariables and baseColor determine the generated theme tokens.