The components.json file is the central configuration artifact for the shadcn CLI system. It defines how the CLI behaves in the context of a project, providing critical information about component styles, import aliases, Tailwind CSS setup, registry endpoints, and feature flags such as React Server Components (RSC) or Right-to-Left (RTL) support.
This page details the schema, resolution, validation, and usage of components.json within the CLI, describing how its contents influence component installation, code transformation, theming, and registry fetching.
The schema for components.json is defined using the Zod validation library and is strictly enforced to avoid unintentional configuration issues. The main schema is called rawConfigSchema. It ensures all required and optional properties are correctly typed and structured.
components.json File| Property | Type | Schema Details | Description |
|---|---|---|---|
$schema | string (optional) | URL string "https://ui.shadcn.com/schema.json" | JSON Schema URL for editor validation and IDE autocompletion |
style | string | e.g., "new-york", "base-nova" | Defines the component style variant (immutable after init) |
rsc | boolean | Defaults to false | Use React Server Components, enabling 'use client' directive auto-injection |
tsx | boolean | Defaults to true | Enables TypeScript components (true) or JavaScript components (false) |
tailwind | object | See next for individual fields | Tailwind CSS configuration — key for theming and styling |
tailwind.config | string (optional) | Relative path ("tailwind.config.js" or "tailwind.config.ts") | Tailwind config path (leave empty for Tailwind v4) |
tailwind.css | string | Relative path to stylesheet | The CSS file importing Tailwind base styles (like globals.css) |
tailwind.baseColor | string | Named base color palette (e.g., "neutral", "zinc", "mauve") | Controls default semantic color tokens |
tailwind.cssVariables | boolean | Defaults to true | Enables generation of CSS variables vs inline literal Tailwind classes |
tailwind.prefix | string (optional) | Defaults to empty string ("") | CSS class prefix for Tailwind utilities (e.g., "tw-") |
iconLibrary | string (optional) | "lucide" or "radix" | Selects the default icon library, with inferred defaults if omitted |
rtl | boolean | Defaults to false | Enables Right-to-Left layout support |
menuColor | enum (optional) | E.g., "default", "inverted", "default-translucent", "inverted-translucent" | Controls menu color variants |
menuAccent | enum (optional) | "subtle" or "bold" | Accent style for menus |
aliases | object | "components", "utils", "ui", "lib", "hooks" aliases | Defines import prefixes for components and utility directories |
registries | object (optional) | Custom registry configuration, validated separately as registryConfigSchema | Allows configuring multiple custom component registries |
Sources: packages/shadcn/src/utils/get-config.ts31-44 packages/shadcn/src/utils/get-config.ts99-115 apps/v4/public/schema.json1-141
Configuration loading uses the cosmiconfig library to locate and parse components.json from the current working directory (cwd).
getConfigThe getConfig function is the main entry point to load the parsed and resolved config. It performs path resolution to turn aliases into absolute filesystem paths.
getRawConfig(cwd) which uses cosmiconfig to find components.json.iconLibrary is not specified, it defaults based on the style.resolveConfigPaths(cwd, config), which processes aliases using tsconfig-paths or package imports.Configuration System Entity Map
Sources: packages/shadcn/src/utils/get-config.ts26-28 packages/shadcn/src/utils/get-config.ts32-45 packages/shadcn/src/utils/get-config.ts47-116
The resolveAliasPath function transforms alias strings (e.g., @/components) into absolute filesystem paths. It is sensitive to whether an alias is backed by a package import or a workspace export.
| Alias | Resolution and Fallback Logic |
|---|---|
components | Must resolve explicitly via alias; resolved to absolute filesystem path |
utils | Must resolve explicitly |
ui | Fallback: <resolved_components>/ui |
lib | Fallback: directory one-level above utils |
hooks | Fallback: directory at <resolved_components>/../hooks |
Sources: packages/shadcn/src/utils/get-config.ts69-90 packages/shadcn/src/utils/get-config.ts118-163
The registries property allows users to define custom sources for components. The CLI merges these with BUILTIN_REGISTRIES (like @shadcn) but prevents users from overriding protected namespaces.
Sources: packages/shadcn/src/utils/get-config.ts206-216 packages/shadcn/src/registry/api.ts153-192 packages/shadcn/src/utils/registries.ts1-50
Configuration properties directly influence command execution across the CLI:
| Property | Command Impact | Logic Location |
|---|---|---|
style | Determines registry source paths (e.g., /styles/new-york/button.json) | packages/shadcn/src/registry/api.test.ts70-71 |
rtl | Appends ?rtl=true to registry requests and triggers RTL code transforms | packages/shadcn/src/commands/init.ts110-112 |
iconLibrary | Triggers icon conversion transformers during add | packages/shadcn/src/utils/get-config.ts39-42 |
tailwind.config | If empty, CLI treats project as Tailwind v4 | packages/shadcn/src/utils/get-project-info.ts61-62 |
registries | Configures headers/auth for private registry fetching | packages/shadcn/src/registry/api.ts74-87 |
During shadcn init, the CLI prompts for a "base" (Radix, Base UI, or Aria) and a "preset". These selections populate the initial components.json. The resolveRegistryBaseConfig function uses a "shadow config" to fetch the remote registry:base configuration associated with a preset before writing the local file.
Sources: packages/shadcn/src/commands/init.ts187-200 packages/shadcn/src/preset/presets.ts145-158 packages/shadcn/src/preset/presets.ts225-271
The CLI does not just read the JSON file; it "resolves" it into a Config object that contains absolute paths and merged registry metadata. This resolved object is passed to transformers and updaters.
rawConfigSchema for the file on disk and configSchema for the in-memory resolved object.registries key conflicts with BUILTIN_REGISTRIES.getWorkspaceConfig detects if the project is a monorepo by checking if aliases resolve outside the current package root.Sources: packages/shadcn/src/utils/get-config.ts194-227 packages/shadcn/src/utils/get-config.ts47-116 packages/shadcn/src/utils/get-config.ts229-231
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.