The components.json file is the central nervous system of your shadcn/ui setup. It tells the CLI where to put files, how to structure imports, and what styling approach to use. Understanding this file is crucial because it controls how every component gets added to your project.

Let's explore what this file does and how to configure it for your specific needs.

A Complete components.json Example

Here's what a typical components.json file looks like:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}

Let's break down each section and understand what it controls.

Schema Validation

The schema reference provides IDE support with autocompletion and validation. This helps prevent configuration errors and makes it easier to discover available options.

{
  "$schema": "https://ui.shadcn.com/schema.json"
}

When you have this schema reference, your editor will:

• Provide autocompletion for configuration options
• Validate your configuration and show errors
• Display documentation for each field
• Suggest valid values for enum fields

Style Configuration

The style field determines which visual style variant to use. Currently, shadcn/ui primarily uses "default", but this field allows for future style variants or custom themes.

{
  "style": "default"
}

This configuration affects:

• The base component styling
• Default color schemes
• Typography choices
• Spacing and sizing defaults

React Server Components Support

The rsc (React Server Components) flag tells the CLI whether your project uses React Server Components. This affects how components are generated. When set to true, client-side components are generated with "use client" directives when needed.

{
  "rsc": true
}

TypeScript Configuration

The tsx field determines whether components are generated as TypeScript (.tsx) or JavaScript (.jsx) files. When set to true, components include full TypeScript type definitions and interfaces.

{
  "tsx": true
}

Most developers should use tsx: true for the superior developer experience.

Tailwind CSS Configuration

The tailwind section is the most complex part of the configuration:

{
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
  }
}

Config File Path

When using an older version of shadcn/ui, this tells the CLI where your Tailwind configuration file is located e.g. tailwind.config.js. The CLI needs to modify this file to add component-specific configuration. Starting from the fourth major update of shadcn/ui, this is not needed as Tailwind uses the globals.css file instead.

{
  "config": ""
}

CSS File Path

This specifies where your global CSS file is located. The CLI will add CSS custom properties and base styles to this file.

{
  "css": "app/globals.css"
}

Base Color

The base color determines the default neutral color palette for your components.

{
  "baseColor": "slate"
}

Available options include:

• slate
• gray
• zinc
• neutral
• stone

This affects the appearance of borders, muted text, and other neutral elements throughout your components.

CSS Variables

This is a crucial setting that determines how your design system is implemented. When set to true, design tokens are implemented as CSS custom properties.

{
  "cssVariables": true
}

This makes it easy to customize and theme your components. Most projects should use cssVariables: true for maximum flexibility.

Tailwind Prefix

If your Tailwind configuration uses a prefix (e.g., tw-), specify it here. The CLI will ensure all generated classes use the correct prefix.

{
  "prefix": ""
}

Specifying a prefix of tw- would generate classes like tw-bg-primary instead of bg-primary.

Path Aliases

Path aliases determine where components and utilities are placed in your project:

{
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}

Components Alias

This tells the CLI where to place component files.

{
  "components": "@/components"
}

With this configuration:

npx shadcn@latest add button

Will create: components/ui/button.tsx

Utils Alias

This specifies where utility functions are located.

{
  "utils": "@/lib/utils"
}

Components will import the cn function from this path:

import { cn } from "@/lib/utils"

The CLI's Role

The components.json file is consumed by the shadcn/ui CLI to:

1. Determine file placement: Where to create component files
2. Configure imports: How components should import utilities and other dependencies
3. Apply styling: Which classes and styling approach to use
4. Update configuration: How to modify your Tailwind config and CSS files
5. Handle TypeScript: Whether to generate TypeScript or JavaScript files

Initializing components.json

You can create a components.json file using the CLI:

npx shadcn@latest init

This command will:

1. Ask you questions about your project setup
2. Generate a components.json file based on your answers
3. Update your tailwind.config.js file
4. Add necessary CSS custom properties to your global CSS file
5. Create a lib/utils.ts file with the cn utility function

The interactive setup ensures your configuration matches your project structure and preferences.

Modifying Your Configuration

You can update your components.json file at any time. Changes will affect newly added components, but won't modify existing components automatically.

If you change fundamental settings (like cssVariables or baseColor), you may need to:

1. Regenerate existing components
2. Update your global CSS file
3. Modify your Tailwind configuration

Configuration Best Practices

1. Use TypeScript: Set tsx: true for better developer experience
2. Enable CSS variables: Set cssVariables: true for maximum flexibility
3. Choose appropriate RSC setting: Match your React setup
4. Use semantic aliases: Stick with @/components and @/lib/utils for consistency
5. Document your choices: Add comments to explain project-specific decisions

What's Next

Now that you understand how components.json configures your entire shadcn/ui setup, you're ready to dive deeper into the foundation that makes it all possible. In the next section, we'll explore Radix UI primitives – the accessible, unstyled components that provide the robust behavior underlying every shadcn/ui component.

Understanding primitives is crucial because they're what makes shadcn/ui components so reliable and accessible. They handle all the complex interaction patterns so you can focus on styling and customization.