Block folder structure location
A block folder must be created in the apps/www/registry/new-york/blocks directory with a kebab-case name. The build script will handle building the block for the default style.
blocks/setup
167 notes in this subject, read out of this brain and free to use. This is page 1 of 3.
Setup commands for block development workspace
To set up a workspace for contributing blocks: git clone https://github.com/shadcn-ui/ui.git, then git checkout -b username/my-new-block, then pnpm install, then pnpm www:dev to start the dev server.
v0 access requires Vercel account
To use v0, you must sign up for a free Vercel account. A Vercel account also provides free access to Vercel's frontend cloud platform for deploying and hosting projects.
tailwind.config path configuration
The tailwind.config property specifies the path to your tailwind.config.js or tailwind.config.ts file. For Tailwind CSS v4, leave this property blank.
components.json $schema property
The $schema property should point to https://ui.shadcn.com/schema.json to validate the components.json configuration file.
aliases.utils import alias
The aliases.utils property specifies the import alias for utility functions, such as '@/lib/utils'.
tailwind.prefix configuration
The tailwind.prefix property specifies a prefix to use for Tailwind CSS utility classes. Components will be added with this prefix. For example, setting it to 'tw-' will prefix all utility classes.
rsc configuration 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.
aliases.ui import alias
The aliases.ui property specifies the import alias for ui components. The CLI uses this value to determine where to place ui components. For example, '@/app/ui' will place ui components in that directory.
tsconfig.json paths setup for aliases
To back aliases with compilerOptions.paths, configure your tsconfig.json with baseUrl and paths like: { 'compilerOptions': { 'baseUrl': '.', 'paths': { '@/*': ['./src/*'] } } }. Ensure your aliases include the src directory when applicable.
aliases.components import alias
The aliases.components property specifies the import alias for components, such as '@/components'.
components.json style property
The style property specifies the component style for your project. The only valid option is 'new-york'. The 'default' style has been deprecated. This property cannot be changed after initialization.
components.json file purpose
The components.json file holds configuration for your project and is used by the CLI to understand how your project is set up and how to generate components customized for your project. This file is only required if you are using the CLI to add components; the copy and paste method does not require it.
aliases purpose in components.json
The aliases object tells the CLI which import roots map to components, ui, lib, hooks, and utils. The CLI uses these values to place generated components in the correct location and rewrite imports. Aliases can be backed by either compilerOptions.paths in tsconfig.json/jsconfig.json or package.json#imports with TypeScript package import resolution enabled.
tailwind.css path configuration
The tailwind.css property specifies the path to the CSS file that imports Tailwind CSS into your project, such as 'styles/global.css'.
tsx configuration for TypeScript or JavaScript
The tsx property chooses between TypeScript and JavaScript components. When set to true, components are added as TypeScript with .ts or .tsx file extensions. When set to false, components are added as JavaScript with .jsx file extensions.
aliases.lib import alias
The aliases.lib property specifies the import alias for lib functions such as format-date or generate-id, such as '@/lib'.
tailwind.cssVariables configuration
The tailwind.cssVariables property controls theme token generation. When set to true, semantic theme tokens like 'background', 'foreground', and 'primary' are generated as CSS variables. When set to false, inline Tailwind color utilities are generated instead. This property cannot be changed after initialization; to switch between CSS variables and utility classes, you must delete and reinstall your components.
tailwind.baseColor property values
The tailwind.baseColor property determines which base color is used to generate default theme tokens for components. Valid options are: neutral, stone, zinc, mauve, olive, mist, and taupe. This property cannot be changed after initialization.
aliases.hooks import alias
The aliases.hooks property specifies the import alias for hooks such as use-media-query or use-toast, such as '@/hooks'.
AI-Ready principle - open code for AI models
shadcn/ui is designed to be AI-ready. The open code and consistent API allow AI models to read, understand, and even generate new components. An AI model can learn how your components work and suggest improvements or even create new components that integrate with your existing design.
Distribution principle - schema and CLI for component distribution
shadcn/ui is a code distribution system with two components: a flat-file schema that defines the components, their dependencies, and properties, and a CLI command-line tool to distribute and install components across projects with cross-framework support. The schema can be used to distribute your own components to other projects or have AI generate completely new components based on the existing schema.
Composition principle - common composable interface
Every component in shadcn/ui shares a common, composable interface. If a component does not exist, shadcn/ui brings it in, makes it composable, and adjusts its style to match and work with the rest of the design system. This means a shared, composable interface is predictable for both teams and LLMs, and you are not learning different APIs for every new component, even for third-party ones.
shadcn/ui is not a component library but a code distribution platform
shadcn/ui is not a traditional component library that you install from NPM and use directly. Instead, it is a platform for how you build your own component library. You receive the actual component code with full control to customize and extend components to your needs.
Open Code principle - components are open for modification
The top layer of your component code in shadcn/ui is open for modification. This gives you full transparency to see exactly how each component is built, easy customization to modify any part of a component to fit your design and functionality requirements, and direct access to the code for LLMs to read, understand, and improve components.
Beautiful Defaults principle - carefully chosen default styles
shadcn/ui comes with a large collection of components that have carefully chosen default styles. The components are designed to look good on their own and to work well together as a consistent system. This provides good out-of-the-box appearance with a clean and minimal look without extra work, unified design where components naturally fit with one another, and easy customization to override and extend the defaults.
components.json structure for JavaScript projects
A components.json file with tsx set to false enables JavaScript usage. The configuration includes style (e.g., 'new-york'), rsc (false for non-React Server Components), tailwind settings with config path and css file, baseColor (e.g., 'zinc'), cssVariables enabled, iconLibrary (e.g., 'lucide'), and path aliases for components, utils, ui, lib, and hooks directories.
tsx flag to opt out of TypeScript
To use JavaScript instead of TypeScript in your shadcn/ui project, set the tsx property to false in your components.json configuration file.
JavaScript version available via CLI
shadcn/ui provides a JavaScript version of components available through the CLI. The project is primarily written in TypeScript, but JavaScript alternatives are available.
jsconfig.json import alias configuration
For JavaScript projects, configure import aliases in jsconfig.json with compilerOptions.paths. The example maps '@/*' to './*' to enable clean imports like '@/components'.
Legacy docs for Tailwind v3
The legacy documentation for shadcn/ui with Tailwind v3 is available at https://v3.shadcn.com. The current documentation is for shadcn/ui with Tailwind v4.
Package imports overview
The shadcn CLI supports package imports for installing components, rewriting imports, and resolving third-party registries. Package imports let you use private `#...` import aliases from your `package.json` instead of `compilerOptions.paths` in `tsconfig.json`.
Package import syntax
Package import specifiers must start with `#`. Use TypeScript 5 or later with `moduleResolution: "bundler"` and `resolvePackageJsonImports: true`.
Troubleshooting package imports
If TypeScript cannot resolve a `#...` import, check that: the specifier starts with `#`, the `imports` entry is in the nearest `package.json`, `moduleResolution` is set to `bundler`, `resolvePackageJsonImports` is enabled, and the matching target exists after components are added. If a component is installed but imports still point to `@/...`, check that `components.json` uses the same `#...` aliases as your package imports.
File extensions in package.json imports
The target pattern in `package.json#imports` controls whether generated imports include file extensions. If the target pattern includes the extension (e.g., `"#components/*": "./src/components/*.tsx"`), generated imports omit the extension (e.g., `import { Button } from "#components/ui/button"`). If the target pattern omits the extension (e.g., `"#components/*": "./src/components/*"`), the generated import keeps the source extension (e.g., `import { Button } from "#components/ui/button.tsx"`). For most apps, use the extension in the target pattern.
Monorepo import example with shared UI
When running `add` from the app workspace in a monorepo, app-local files use `#...` imports and shared UI files are imported from the workspace package. Example: `import { Button } from "@workspace/ui/components/button"` and `import { LoginForm } from "#components/login-form"`.
Monorepo shared UI package configuration example
In packages/ui/package.json, configure: `"imports": {"#components/*": "./src/components/*.tsx", "#lib/*": "./src/lib/*.ts", "#hooks/*": "./src/hooks/*.ts"}` and `"exports": {"./globals.css": "./src/styles/globals.css", "./components/*": "./src/components/*.tsx", "./lib/*": "./src/lib/*.ts", "./hooks/*": "./src/hooks/*.ts"}`. In packages/ui/components.json, configure: `"aliases": {"components": "#components", "ui": "#components", "lib": "#lib", "hooks": "#hooks", "utils": "#lib/utils"}`.
Monorepo app workspace configuration example
In apps/web/package.json, configure: `"imports": {"#components/*": "./src/components/*.tsx", "#lib/*": "./src/lib/*.ts", "#hooks/*": "./src/hooks/*.ts"}` and `"dependencies": {"@workspace/ui": "workspace:*"}`. In apps/web/components.json, configure: `"aliases": {"components": "#components", "ui": "@workspace/ui/components", "lib": "#lib", "hooks": "#hooks", "utils": "@workspace/ui/lib/utils"}`.
Monorepo package imports setup
In a monorepo, use package imports for files inside each package and package exports for files shared across workspaces. For the app workspace, configure imports in the app's package.json pointing to local directories, and in components.json use both local `#...` imports and cross-workspace imports like `"@workspace/ui/components"`. For the shared UI package, configure both imports for internal files and exports for files shared across workspaces.
Configure components.json aliases
Use the same `#...` roots in components.json. Example configuration: `"components": "#components"`, `"ui": "#components/ui"`, `"lib": "#lib"`, `"hooks": "#hooks"`, `"utils": "#lib/utils"`. The `ui` alias uses `#components/ui` which is covered by the `#components/*` import in package.json. The `utils` alias uses `#lib/utils` which is covered by `#lib/*`, so you do not need a separate `#utils` import.
Configure TypeScript for package imports
Enable package import resolution in tsconfig.json by setting `moduleResolution` to `"bundler"` and `resolvePackageJsonImports` to `true`. You do not need `compilerOptions.paths` for these aliases.
Configure package.json imports for app
For Next.js, Vite, and TanStack Start apps, configure imports in package.json with entries like `"#components/*": "./src/components/*.tsx"`, `"#lib/*": "./src/lib/*.ts"`, and `"#hooks/*": "./src/hooks/*.ts"`. If your app does not use a `src` directory, remove `src/` from the targets.
components.json aliases with package imports setup
When using package imports, app workspace `components.json` aliases should map: `components` → `#components`, `ui` → `@workspace/ui/components`, `lib` → `#lib`, `hooks` → `#hooks`, `utils` → `@workspace/ui/lib/utils`. UI workspace `components.json` aliases should map: `components` → `#components`, `ui` → `#components`, `lib` → `#lib`, `hooks` → `#hooks`, `utils` → `#lib/utils`.
Shared UI package must export paths for other workspaces
In a monorepo using package imports, the shared UI package (`packages/ui/package.json`) must export any path referenced by another workspace. Example exports: `./globals.css` → `./src/styles/globals.css`, `./components/*` → `./src/components/*.tsx`, `./lib/*` → `./src/lib/*.ts`, `./hooks/*` → `./src/hooks/*.ts`. This allows other workspaces to import through `@workspace/ui/...` paths.
Use package.json#imports for monorepo package imports
For monorepos using package imports instead of `tsconfig.json` paths, use local `#...` aliases for files inside each workspace and workspace package `exports` for shared imports like `@workspace/ui/components`. Example app workspace package.json imports: `#components/*` → `./src/components/*.tsx`, `#lib/*` → `./src/lib/*.ts`, `#hooks/*` → `./src/hooks/*.ts`. Include `"@workspace/ui": "workspace:*"` in dependencies.
Import components from monorepo ui package
Components in a monorepo are imported from the `@workspace/ui` package. For example: `import { Button } from "@workspace/ui/components/button"`. Hooks and utilities can also be imported: `import { useTheme } from "@workspace/ui/hooks/use-theme"` and `import { cn } from "@workspace/ui/lib/utils"`.
Tailwind CSS v4 requires empty config in components.json
For Tailwind CSS v4, leave the `tailwind.config` empty string in the `components.json` file. Do not specify a path to the Tailwind configuration file.
Style, iconLibrary, and baseColor must match across monorepo workspaces
Ensure the same `style`, `iconLibrary`, and `baseColor` values are configured in both `apps/web/components.json` and `packages/ui/components.json` files. Mismatched values can cause inconsistencies in component installation.
components.json aliases configuration for ui workspace
The `packages/ui/components.json` file must define aliases: `components` → `@workspace/ui/components`, `utils` → `@workspace/ui/lib/utils`, `hooks` → `@workspace/ui/hooks`, `lib` → `@workspace/ui/lib`, `ui` → `@workspace/ui/components`. The file must also include `$schema`, `style`, `rsc`, `tsx`, `tailwind`, and `iconLibrary` fields.
Each monorepo workspace requires components.json
Every workspace in a monorepo must have both a `components.json` file and a `package.json` file. The `package.json` tells npm how to install dependencies. The `components.json` file tells the CLI how and where to install components.
Monorepo file structure with workspaces
A monorepo created with `init --monorepo` has this structure: `apps/web` contains the app with `app/page.tsx`, `components/`, `components.json`, and `package.json`. `packages/ui` contains shared components and dependencies with `src/components/`, `src/hooks/`, `src/lib/utils.ts`, `src/styles/globals.css`, `components.json`, and `package.json`. The root contains `package.json` and `turbo.json` for Turborepo configuration.
package.json#imports vs components.json aliases
Use `package.json#imports` for local package-local aliases inside a workspace (e.g., inside `packages/ui`). Use explicit aliases in `components.json` for shared workspace imports like `@workspace/ui/components`. The CLI uses `components.json` aliases to route files across workspace boundaries.
Import and use added components
After adding a component with the CLI, import it from '@/components/ui/[component-name]' and use it in your code. For example, import { Button } from '@/components/ui/button' and then <Button>Click me</Button>.
Component source code is added to project
Unlike traditional component libraries, shadcn/ui adds the component source code directly to your project under components/ui/. You own the code and can customize it however you want.
React 19 support status in shadcn/ui
Full support for React 19 and Tailwind v4 has been added in the latest release. The guide may be outdated, and users should proceed with caution.
recharts package.json override example
Add this to package.json to override react-is for React 19 compatibility with recharts: {"overrides": {"react-is": "^19.0.0-rc-69d4b800-20241021"}}. The react-is version shown is an example and should match your actual React 19 version.
recharts React 19 override requirement
To use recharts with React 19, you must add an override for the react-is dependency in package.json. The react-is version must match the version of React 19 being used. After adding the override, run 'npm install --legacy-peer-deps'.
Peer dependency conflict resolution for npm
When installing packages that do not list React 19 as a peer dependency with npm, you will see an ERESOLVE error. This is npm only; PNPM and Bun show only silent warnings.
npm React 19 installation requires flags
When installing shadcn/ui with npm and React 19, the shadcn CLI will prompt you to select a flag to resolve peer dependency issues. No flags are required for pnpm, bun, or yarn.
Install shadcn/ui skill
Run 'npx skills add shadcn/ui' to install the shadcn skill into your project. Once installed, your AI assistant automatically loads it when working with shadcn/ui components.