--- title: components.json description: Configuration for your project. --- The `components.json` file holds configuration for your project. We use it to understand how your project is set up and how to generate components customized for your project. It is **only required if you're using the CLI** to add components to your project. If you're using the copy and paste method, you don't need this file. You can create a `components.json` file in your project by running the following command: ```bash npx shadcn@latest init ``` See the CLI section for more information. ## $schema You can see the JSON Schema for `components.json` [here](https://ui.shadcn.com/schema.json). ```json title="components.json" { "$schema": "https://ui.shadcn.com/schema.json" } ``` ## style The style for your components. **This cannot be changed after initialization.** ```json title="components.json" { "style": "new-york" } ``` The `default` style has been deprecated. Use the `new-york` style instead. ## tailwind Configuration to help the CLI understand how Tailwind CSS is set up in your project. See the installation section for how to set up Tailwind CSS. ### tailwind.config Path to where your `tailwind.config.js` file is located. **For Tailwind CSS v4, leave this blank.** ```json title="components.json" { "tailwind": { "config": "tailwind.config.js" | "tailwind.config.ts" } } ``` ### tailwind.css Path to the CSS file that imports Tailwind CSS into your project. ```json title="components.json" { "tailwind": { "css": "styles/global.css" } } ``` ### tailwind.baseColor This is used to generate the default theme tokens for your components. **This cannot be changed after initialization.** ```json title="components.json" { "tailwind": { "baseColor": "neutral" | "stone" | "zinc" | "mauve" | "olive" | "mist" | "taupe" } } ``` ### tailwind.cssVariables We use and recommend CSS variables for theming. Set `tailwind.cssVariables` to `true` to generate semantic theme tokens like `background`, `foreground`, and `primary`. Set it to `false` to generate inline Tailwind color utilities instead. ```json title="components.json" { "tailwind": { "cssVariables": `true` | `false` } } ``` For more information, see the theming docs. **This cannot be changed after initialization.** To switch between CSS variables and utility classes, you'll have to delete and re-install your components. ### tailwind.prefix The prefix to use for your Tailwind CSS utility classes. Components will be added with this prefix. ```json title="components.json" { "tailwind": { "prefix": "tw-" } } ``` ## rsc Whether or not to enable support for React Server Components. The CLI automatically adds a `use client` directive to client components when set to `true`. ```json title="components.json" { "rsc": `true` | `false` } ``` ## tsx Choose between TypeScript or JavaScript components. Setting this option to `false` allows components to be added as JavaScript with the `.jsx` file extension. ```json title="components.json" { "tsx": `true` | `false` } ``` ## aliases The CLI uses these values to place generated components in the correct location and rewrite imports. You can back these aliases with either: 1. `compilerOptions.paths` in your `tsconfig.json` or `jsconfig.json` 2. `package.json#imports` with TypeScript package import resolution enabled The aliases in `components.json` are still required when using the CLI. They tell the CLI which import roots map to `components`, `ui`, `lib`, `hooks`, and `utils`. **Important:** If you're using package imports, enable `resolvePackageJsonImports` and use `moduleResolution: "bundler"` in your `tsconfig.json`. If you're using `paths`, make sure your aliases include the `src` directory when applicable. ### Using `tsconfig` or `jsconfig` paths ```json title="tsconfig.json" { "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["./src/*"] } } } ``` ### Using `package.json#imports` Recommended setup for a single-package app: ```json title="package.json" { "imports": { "#components/*": "./src/components/*.tsx", "#lib/*": "./src/lib/*.ts", "#hooks/*": "./src/hooks/*.ts" } } ``` ```json title="tsconfig.json" { "compilerOptions": { "moduleResolution": "bundler", "resolvePackageJsonImports": true } } ``` ```json title="components.json" { "aliases": { "components": "#components", "ui": "#components/ui", "lib": "#lib", "hooks": "#hooks", "utils": "#lib/utils" } } ``` The aliases in `components.json` still tell the CLI where to place `components`, `ui`, `lib`, `hooks`, and `utils`. `package.json#imports` provides the runtime and TypeScript resolution for those `#...` specifiers. The matched `imports` target also controls whether generated `#...` imports keep file extensions: - `"#components/*": "./src/components/*"` preserves source extensions and can generate imports like `#components/button.tsx` - `"#components/*": "./src/components/*.tsx"` strips source extensions and generates imports like `#components/button` For monorepos, see the monorepo docs. Local workspace aliases can use `package.json#imports`, while shared workspace imports such as `@workspace/ui/components` are resolved from the target package's `exports`. For framework-specific setup, see the [package imports guide](/docs/package-imports). ### aliases.utils Import alias for your utility functions. ```json title="components.json" { "aliases": { "utils": "@/lib/utils" } } ``` ### aliases.components Import alias for your components. ```json title="components.json" { "aliases": { "components": "@/components" } } ``` ### aliases.ui Import alias for `ui` components. The CLI will use the `aliases.ui` value to determine where to place your `ui` components. Use this config if you want to customize the installation directory for your `ui` components. ```json title="components.json" { "aliases": { "ui": "@/app/ui" } } ``` ### aliases.lib Import alias for `lib` functions such as `format-date` or `generate-id`. ```json title="components.json" { "aliases": { "lib": "@/lib" } } ``` ### aliases.hooks Import alias for `hooks` such as `use-media-query` or `use-toast`. ```json title="components.json" { "aliases": { "hooks": "@/hooks" } } ``` ## registries Configure multiple resource registries for your project. This allows you to install components, libraries, utilities, and other resources from various sources including private registries. See the Namespaced Registries documentation for detailed information. ### Basic Configuration Configure registries with URL templates: ```json title="components.json" { "registries": { "@v0": "https://v0.dev/chat/b/{name}", "@acme": "https://registry.acme.com/{name}.json", "@internal": "https://internal.company.com/{name}.json" } } ``` The `{name}` placeholder is replaced with the resource name when installing. ### Advanced Configuration with Authentication For private registries that require authentication: ```json title="components.json" { "registries": { "@private": { "url": "https://api.company.com/registry/{name}.json", "headers": { "Authorization": "Bearer ${REGISTRY_TOKEN}", "X-API-Key": "${API_KEY}" }, "params": { "version": "latest" } } } } ``` Environment variables in the format `${VAR_NAME}` are automatically expanded from your environment. ### Using Namespaced Registries Once configured, install resources using the namespace syntax: ```bash # Install from a configured registry npx shadcn@latest add @v0/dashboard # Install from private registry npx shadcn@latest add @private/button # Install multiple resources npx shadcn@latest add @acme/header @internal/auth-utils ``` ### Example: Multiple Registry Setup ```json title="components.json" { "registries": { "@shadcn": "https://ui.shadcn.com/r/{name}.json", "@company-ui": { "url": "https://registry.company.com/ui/{name}.json", "headers": { "Authorization": "Bearer ${COMPANY_TOKEN}" } }, "@team": { "url": "https://team.company.com/{name}.json", "params": { "team": "frontend", "version": "${REGISTRY_VERSION}" } } } } ``` This configuration allows you to: - Install public components from shadcn/ui - Access private company UI components with authentication - Use team-specific resources with versioning For more information about authentication, see the Authentication documentation.