components.json

Purpose and Scope

The project configuration file is the local contract between an application and the shadcn CLI. It tells the CLI where generated files belong, how imports should be written, which Tailwind assets should be updated, and which component style assumptions are already present in the app. The configuration matters because shadcn/ui distributes source code rather than a closed component package: adding a component means copying files into the project and making them fit the project’s own aliases, CSS entry point, styling mode, and framework choices. The changelog for the rewritten CLI explicitly instructs existing projects to update this file with import aliases for components, utilities, UI components, library code, and hooks, because those aliases are used during installation and migration workflows.

Sources: apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx

The file is also the place where a project records preferences that later commands must preserve. Newer workflows such as create, apply, and eject assume that an existing project already carries enough local configuration to safely transform code without starting over. The create announcement frames the CLI as a customization system: the user can pick a component library, icons, base color, theme, fonts, and a visual style, and the CLI rewrites component code to match those choices. The apply announcement then explains that preset switching updates theme, colors, CSS variables, fonts, and icons while keeping the current base and right-to-left settings from the project. In practice, this means the configuration should be treated as state, not just as installation metadata.

Sources: apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx, apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx

Relevant Source Files

apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx — documents the rewritten CLI, the role of components.json during upgrades, and the alias keys that existing projects must add.
apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx — explains resolve-anywhere behavior, where installed files are tracked and imports are resolved across aliases and non-fixed file layouts.
apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx — describes create-time customization across component library, icons, base color, theme, fonts, and visual style, which are the kinds of choices represented by project configuration.
apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx — describes applying presets to existing projects while preserving current base and RTL settings.
apps/v4/content/docs/changelog/2026-05-shadcn-eject.mdx — documents how shared Tailwind CSS is imported during init and later inlined by eject, including the monorepo path option for the workspace containing components.json and global CSS.
apps/v4/content/docs/components/aria/field.mdx — shows how installed components are consumed through the configured UI alias and how manual installation requires updating import paths to match the project setup.

Configuration Fields Reference

Use this reference as the shape of the public configuration contract. The exact values vary by framework and by CLI generation path, but the responsibility of each field is stable: schema metadata validates the file, style and library choices select component source transformations, Tailwind settings point at CSS and design tokens, aliases control import rewriting, and framework flags decide whether generated files should be TypeScript, TSX, and React Server Component aware.

Field	Purpose	Notes
`$schema`	Points editors and validators to the shadcn configuration schema.	The changelog example uses the public schema URL.
`style`	Selects the visual style baseline used by generated components.	The upgrade example shows `new-york`; create-era docs describe newer named visual styles.
`rsc`	Records whether the target React app uses React Server Components conventions.	The CLI uses this when choosing client boundaries and component output.
`tsx`	Records whether generated React files should use TSX rather than JavaScript JSX.	JavaScript projects use this differently from TypeScript-first projects.
`tailwind`	Groups Tailwind integration settings.	Includes the CSS entry point, optional config file, base color, CSS variable mode, and prefix settings.
`tailwind.config`	Points to the Tailwind config file when the framework uses one.	The CLI rewrite update says installed components can update Tailwind configuration instead of overwriting it.
`tailwind.css`	Points to the global stylesheet that should receive imports, variables, and shared utilities.	Eject operates from the workspace containing this file and the project configuration.
`tailwind.baseColor`	Selects the default color palette foundation.	Create and apply workflows discuss base color and theme updates.
`tailwind.cssVariables`	Chooses whether theme colors are emitted as CSS variables.	Apply updates CSS variables when presets change.
`tailwind.prefix`	Records a class prefix for projects that namescope Tailwind utilities.	Components must be transformed so generated classes match the app.
`aliases`	Groups import targets for generated code.	The rewritten CLI requires explicit aliases for major code areas.
`aliases.components`	Base path for application components.	The changelog upgrade example maps this to an app components directory.
`aliases.ui`	Path for shadcn UI component files.	Component usage examples import from this location.
`aliases.utils`	Path for shared utility helpers.	Used when generated components import class-name utilities.
`aliases.lib`	Path for general library code.	Added in the rewritten CLI upgrade guidance.
`aliases.hooks`	Path for generated or shared hooks.	Added in the rewritten CLI upgrade guidance.
`iconLibrary`	Selects the icon package or icon set used by generated components.	Create and apply workflows mention icons as preset-controlled project choices.
`base`	Records the selected component implementation family when present.	Create-era docs describe choosing Radix or Base UI while keeping compatible abstractions.
`registries`	Defines named registry sources when present.	Registry-aware workflows use names, URLs, and authentication separately from local aliases.

A minimal modern configuration usually contains schema metadata, a style, framework flags, Tailwind settings, and aliases. The most important operational rule is that alias values must agree with the project’s TypeScript or bundler path mapping. If the configuration says UI components live under an at-sign UI path but the compiler does not resolve that path, generated code may look correct while the app fails to build. The August 2024 migration guidance calls out this alignment directly by telling users with a different alias prefix to replace the at-sign prefix with their own prefix.

Sources: apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx

components.json

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

Aliases, Imports, and Resolve-Anywhere Installation

Aliases are the highest-impact part of the file because they determine what the generated source code will look like after installation. The Field documentation demonstrates the normal result: consumers import the installed component family from the UI alias, then compose the copied primitives directly in application code. The manual installation instructions make the same point from the opposite direction: if a user copies a component by hand, they must update import paths to match their own project setup. The CLI automates that rewrite, but it can only do so if the configuration describes the project accurately.

Sources: apps/v4/content/docs/components/aria/field.mdx

The resolve-anywhere release makes this alias contract more flexible. Earlier component distributions often assumed a predictable directory layout, but the 2.5.0 changelog says registries can now place files anywhere in an app, including outside the registry itself. On installation, the CLI tracks files and performs multi-pass resolution to handle imports and aliases. That means the aliases field is not only a template variable for a single component file. It is part of a broader graph rewrite where the installer needs to understand every generated file, every local dependency, and the final path that each import should take in the consuming application.

Sources: apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx

In monorepos, aliases should describe the package that owns the generated files, not merely the repository root. The eject changelog gives a concrete operational example: run the command from the workspace that contains the project configuration and the global CSS file, or pass the configuration location with the command option. The same mental model applies when adding components. If a shared UI package owns the configuration, its aliases should point at directories inside that package, while the consuming app may import the shared package through its own workspace dependency or package import map.

Sources: apps/v4/content/docs/changelog/2026-05-shadcn-eject.mdx

Tailwind, CSS Variables, and Shared CSS

The Tailwind group controls how copied components join the app’s styling system. The August 2024 CLI rewrite emphasizes that installing a component can update existing Tailwind files rather than overwriting them, and gives the accordion as an example of a component shipping its own dependencies such as keyframes. That behavior depends on knowing where Tailwind configuration and global CSS live. If the config file path is wrong, generated animations, theme extensions, or content scanning changes may be written to the wrong place or skipped. If the CSS entry path is wrong, base imports and variable definitions may not reach the running application.

Sources: apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx

The CSS entry is especially important in the current styling model because init adds a shared stylesheet import for shadcn utilities. The eject changelog explains why that file exists: both Radix and Base UI implementations need shared Tailwind utilities, custom variants such as open and closed states, utilities such as no-scrollbar, and shared fixes that are easier to maintain in one place. The import behaves like other build-time CSS imports and can be tree-shaken in production. If a team does not want the runtime dependency, eject inlines the shared CSS into the configured global stylesheet and removes the package dependency.

Sources: apps/v4/content/docs/changelog/2026-05-shadcn-eject.mdx

CSS variables and base colors are configuration-level decisions because they affect every generated component, not only the current theme file. The apply workflow demonstrates this by reinstalling existing components while updating theme, colors, CSS variables, fonts, and icons. A preset can be generated with different values, but the command keeps the current base and RTL settings from the existing project. This is an important edge case: project configuration acts as a guardrail so a preset can refresh design tokens without unintentionally switching foundational implementation choices that would require deeper code review.

Sources: apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx

Framework Flags, Component Families, and Presets

The framework flags decide how component code should be emitted for the target runtime. A React Server Components aware project needs different client boundary treatment than a purely client-rendered Vite app, and a TypeScript project expects typed TSX files rather than plain JSX. The CLI rewrite announcement says init now supports major React frameworks out of the box and performs framework detection, including creating a new Next.js app in one command. That detection supplies defaults, but the configuration remains the durable record that later add, apply, and eject commands read when they need to modify the same project again.

Sources: apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx

Component family and preset choices broaden the file beyond framework detection. The create announcement says users can choose between Radix and Base UI while keeping the same abstraction, and that components pulled from remote registries remain compatible because the CLI detects the library and applies the right transformations. This is why a configuration field that records the selected base implementation is more than a label. It tells future installs which source variant and import strategy should be used, and it helps prevent a project from accidentally mixing implementation families in a way that changes behavior or bundle expectations.

Sources: apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx

Practical Workflow and Next Steps

When starting a project, let the CLI generate the file when possible, then review every path before committing. Confirm that the global CSS entry exists, that the Tailwind config path matches the framework version, that TypeScript or bundler aliases resolve the same prefixes, and that the UI alias points to the directory where copied components should live. After that, add a small component and verify both import resolution and styling. The Field component is a useful smoke test because it imports many sibling primitives from the UI alias and is intended to compose with form controls, labels, descriptions, and validation messages.

Sources: apps/v4/content/docs/components/aria/field.mdx

For existing projects, treat configuration changes as migrations. First add any missing aliases from the rewritten CLI guidance, replacing the prefix to match your own path system. Next, run component installation or preset application from the workspace that owns the configuration. Finally, review generated diffs in three places: copied component files, Tailwind or CSS assets, and package dependencies. If you are moving to a preset, expect changes to theme, colors, variables, fonts, and icons. If you are ejecting shared CSS, expect the global stylesheet to grow while the shadcn dependency is removed.

Sources: apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx, apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx, apps/v4/content/docs/changelog/2026-05-shadcn-eject.mdx

Read the CLI page next for command-level behavior, especially init, add, apply, and eject. Read the package imports page if your project uses import maps or monorepo package boundaries, because those must agree with the aliases recorded here. Read the theming and Tailwind pages when changing base colors, CSS variable mode, or shared utility imports. For registry authors, separate this file from registry metadata: components.json describes the consuming project, while registry.json describes a registry endpoint and the items it publishes.

Ask a question...