advanced topics

42 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Use cases for local file support

Local file support enables zero setup without remote registries, faster development by testing registry items locally before publishing, enhanced workflows for agents and MCP by generating and running registry items locally, and keeping proprietary components local and private.

Supported frameworks for shadcn create

npx shadcn create is available for Next.js, Vite, TanStack Start, and v0.

Five new visual styles in shadcn create

shadcn/ui offers five visual styles: Vega (the classic shadcn/ui look), Nova (reduced padding and margins for compact layouts), Maia (soft and rounded with generous spacing), Lyra (boxy and sharp, pairs well with mono fonts), and Mira (compact, made for dense interfaces).

npx shadcn create CLI tool overview

The npx shadcn create command allows you to customize everything and create your own version of shadcn/ui. You can pick your component library, icons, base color, theme, fonts, and visual style. The config rewrites component code to match your setup, adapting fonts, spacing, structure, and libraries to your preferences.

Component library options in shadcn create

shadcn create allows you to choose between Radix and Base UI as your component library. Every component has been rebuilt for Base UI while keeping the same abstraction. Both options are fully compatible with existing components, including those pulled from remote registries.

Auto-detection and transformation in shadcn create

When you pull down components with shadcn create, the system auto-detects your library and applies the right transformations automatically.

tailwind.baseColor configuration

The tailwind.baseColor property is used to generate the default theme tokens for your components and cannot be changed after initialization. Valid values are: neutral, stone, zinc, mauve, olive, mist, or taupe.

tailwind.cssVariables configuration

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. This cannot be changed after initialization; to switch between CSS variables and utility classes, you must delete and re-install your components.

tailwind.prefix configuration

The tailwind.prefix property specifies the prefix to use for your Tailwind CSS utility classes. Components will be added with this prefix.

rsc property for React Server Components

The rsc property enables or disables support for React Server Components. When set to true, the CLI automatically adds a 'use client' directive to client components. Valid values are true or false.

tsx property for TypeScript or JavaScript

The tsx property allows you to choose between TypeScript or JavaScript components. Setting this option to false allows components to be added as JavaScript with the .jsx file extension. Valid values are true or false.

aliases configuration in components.json

The CLI uses aliases to place generated components in the correct location and rewrite imports. Aliases can be backed by either compilerOptions.paths in tsconfig.json or jsconfig.json, or by package.json#imports with TypeScript package import resolution enabled. The aliases in components.json are still required when using the CLI.

aliases.utils configuration

The aliases.utils property specifies the import alias for your utility functions. Example: '@/lib/utils'

aliases.components configuration

The aliases.components property specifies the import alias for your components. Example: '@/components'

aliases.ui configuration

The aliases.ui property specifies the import alias for ui components. The CLI will use this value to determine where to place your ui components, allowing you to customize the installation directory.

aliases.lib configuration

The aliases.lib property specifies the import alias for lib functions such as format-date or generate-id.

aliases.hooks configuration

The aliases.hooks property specifies the import alias for hooks such as use-media-query or use-toast.

registries configuration for multiple sources

Configure multiple resource registries in components.json to install components, libraries, utilities, and other resources from various sources including private registries. Registries can be configured with URL templates where {name} is replaced with the resource name when installing.

registries with basic URL configuration

Basic registry configuration uses URL templates with the {name} placeholder that gets replaced with the resource name. Example: '@v0': 'https://v0.dev/chat/b/{name}'

registries with authentication headers

Private registries can be configured with authentication by specifying an object with url, headers, and params properties. Environment variables in the format ${VAR_NAME} are automatically expanded from your environment.

Install from namespaced registries

Once configured, install resources using the namespace syntax. Examples: npx shadcn@latest add @v0/dashboard, npx shadcn@latest add @private/button, npx shadcn@latest add @acme/header @internal/auth-utils

tsconfig paths with package imports

When using package imports, enable resolvePackageJsonImports and use moduleResolution: 'bundler' in your tsconfig.json. If using paths, make sure your aliases include the src directory when applicable.

package.json imports with file extensions

The matched imports target controls whether generated imports keep file extensions. Using '@/components/*': './src/components/*' preserves source extensions and can generate imports like '@/components/button.tsx', while '@/components/*': './src/components/*.tsx' strips source extensions and generates imports like '@/components/button'.

tailwind.css path configuration

The tailwind.css property specifies the path to the CSS file that imports Tailwind CSS into your project.

components.json is optional with CLI only

The components.json file 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.

Create components.json with init command

You can create a components.json file in your project by running the command: npx shadcn@latest init

components.json schema reference

The JSON Schema for components.json is available at https://ui.shadcn.com/schema.json and can be added to the components.json file with the $schema property.

style property in components.json

The style property specifies the style for your components and cannot be changed after initialization. The value should be 'new-york'. The default style has been deprecated and should not be used.

tailwind.config path configuration

The tailwind.config property specifies the path to where your tailwind.config.js or tailwind.config.ts file is located. For Tailwind CSS v4, leave this property blank.

CLI can detect tailwind.config.ts

The CLI can now detect tailwind.config.ts and add the TypeScript version of the config automatically.

CLI support for custom Tailwind prefix

The CLI can now be configured with a custom Tailwind prefix, and it will automatically prefix utility classes when adding components. This allows adding shadcn/ui components to existing projects like Docusaurus and Nextra without conflicts. It works with cn, cva and CSS variables.

New CLI rewrite August 2024 - npx shadcn init

A complete CLI rewrite was released in August 2024 with support for all major React frameworks (Next.js, Remix, Vite, and Laravel). The new CLI supports installing components, themes, hooks, utils and more using `npx shadcn add`. When initializing into a new app, the CLI updates existing Tailwind files instead of overriding them.

Install remote components using URL with npx shadcn add

Remote components can be installed using a URL with the command `npx shadcn add https://acme.com/registry/navbar.json`.

Initialize new Next.js app directly with npx shadcn init

The improved init command supports framework detection and can initialize a brand new Next.js app in one command using `npx shadcn init`. The init command can also accept component arguments, for example `npx shadcn init sidebar-01 login-01`.

New component registry schema with URL support

A new schema is available that allows shipping your own component registry. The schema has support for URLs, enabling distribution of private components.

Update components.json with import aliases for new CLI

To update an existing project to use the new CLI, the `components.json` file must include import aliases for components, utils, ui, lib, and hooks. The required aliases object should contain: "components": "@/components", "utils": "@/lib/utils", "ui": "@/components/ui", "lib": "@/lib", and "hooks": "@/hooks". If using a different import alias prefix (e.g., ~), replace @ with that prefix.

components.json schema URL for new CLI

The components.json file should reference the schema at "https://ui.shadcn.com/schema.json" using the "$schema" field.

New CLI features include better error handling and monorepo support

The August 2024 CLI rewrite includes improvements such as better error handling and monorepo support.

Components ship their own dependencies in new CLI

In the new CLI, components now ship their own dependencies. For example, the accordion component can define its own Tailwind keyframes. When a component is added to a project, the CLI automatically updates the tailwind.config.ts file accordingly.

shadcn 2.5.0 multi-pass resolution on install

When installing with shadcn 2.5.0, the system tracks all files and performs a multi-pass resolution to correctly handle imports and aliases. This process is designed to be fast.

shadcn 2.5.0 release date

shadcn 2.5.0 was tagged on April 26, 2025.

shadcn 2.5.0 resolve anywhere feature

shadcn 2.5.0 introduces a feature called 'resolve anywhere' that allows registries to place files anywhere in an app. The system will properly resolve imports without requiring a fixed file structure. Files can even be added outside the registry itself.

Give your agent this brain