Installation Overview
Purpose and Scope
The installation section helps readers choose the correct path before they copy commands or edit configuration. shadcn/ui is not presented as a single opaque package installation; the docs guide users toward generating or configuring a project so components, aliases, Tailwind styles, and registry-driven additions land in the right places. The landing page frames three entry points: use shadcn/create, use the CLI, or add shadcn/ui to an existing project. That choice matters because a new project can receive a framework template, while an existing project must preserve its current routing, styling, and import conventions.
Sources: apps/v4/content/docs/installation/index.mdx
For new projects, the first recommendation is shadcn/create. The installation landing page describes it as a visual preset builder that previews choices and produces a framework-specific setup command. This path is meant for readers who have not yet committed to a project scaffold, or who want to decide style, colors, fonts, icons, and related setup options before creating the application. The same model appears in the Astro and Laravel guides, where create generates commands that include the selected template and may include options such as base configuration, monorepo layout, or right-to-left support.
Sources: apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/astro.mdx, apps/v4/content/docs/installation/laravel.mdx
The CLI path is for readers who prefer a terminal-first setup. The landing page documents the general command shape for scaffolding a supported template, and the framework guides show the same pattern in context. For Astro, the CLI can create a new project with the Astro template and can also be passed a monorepo flag. For Laravel, the CLI does not create the Laravel application itself; the Laravel guide instructs users to create the app with the Laravel installer and React starter kit first, then run the shadcn initialization command from the application root.
Sources: apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/astro.mdx, apps/v4/content/docs/installation/laravel.mdx
Core Primitives
The core installation primitives are the project generator, the CLI initializer, the component add command, import aliases, Tailwind CSS, and the project style sheet. The generator and initializer establish the project structure and write configuration. The add command installs individual components into the application after initialization. Import aliases determine how those generated files refer to local component, library, and hook modules. Tailwind CSS and the global style sheet provide the token and utility foundation that the copied components expect. These primitives are visible across the overview, manual setup, and framework-specific guides.
Sources: apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/manual.mdx, apps/v4/content/docs/installation/astro.mdx
Manual installation makes those primitives explicit. It starts by requiring Tailwind CSS, then installs dependencies such as shadcn, class-variance-authority, clsx, tailwind-merge, lucide-react, and tw-animate-css. It then asks the reader to configure aliases either with TypeScript path mapping or with package imports plus TypeScript package import resolution. The manual guide emphasizes that the at-sign alias is a preference, not a requirement, but that package import roots must stay aligned with components.json. That warning is important because the CLI later needs consistent alias information to place and reference generated files correctly.
Sources: apps/v4/content/docs/installation/manual.mdx
The style setup is also a primitive rather than decoration. The manual guide imports Tailwind CSS, animation utilities, and the shadcn Tailwind CSS entry in a global style file. It then defines the dark variant, maps theme colors to CSS variables, and establishes radius and sidebar tokens. This means installation is tied to theming: if the project omits the expected global CSS, components may compile but will not receive the intended color, radius, chart, sidebar, and dark-mode variables. Readers planning deep theme customization should still begin from this foundation and then move to theming documentation.
Sources: apps/v4/content/docs/installation/manual.mdx
Choosing a Setup Path
Choose shadcn/create when the project is new and the reader wants a guided preset. The landing page names this as the recommended route for new projects, and the framework pages show why: the generated command can include the framework template plus selected options. Astro’s guide, for example, sends the reader to a template-specific create URL, then tells them to copy a generated command shaped like a shadcn init command with a preset and template. This is the least manual route because the reader makes choices visually before running the final command.
Sources: apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/astro.mdx
Choose the CLI when the reader already knows the target framework and wants the supported scaffold directly from the terminal. The overview lists supported templates as Next.js, Vite, TanStack Start, React Router, and Astro, while Laravel is treated differently because the app must be created first with Laravel’s own tooling. This distinction prevents a common mistake: assuming every framework can be scaffolded by shadcn itself. The installation overview should therefore be read as a router to a framework guide, not as a replacement for each framework’s detailed setup instructions.
Sources: apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/laravel.mdx
Choose the existing-project path when the application already exists. The landing page says each framework guide includes an Existing Project section with manual setup steps for that framework. Manual installation then supplies the common building blocks: Tailwind, dependencies, aliases, and global CSS. The Gatsby guide illustrates an older or special-case setup style: it targets Gatsby with Tailwind CSS v3, asks users to create or configure a Gatsby project with TypeScript and Tailwind, edits tsconfig paths, adds webpack aliases through gatsby-node, runs shadcn init, and then adds components.
Sources: apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/manual.mdx, apps/v4/content/docs/installation/gatsby.mdx
Framework Coverage and Navigation
The installation navigation metadata lists the framework pages that belong to this section: next, vite, laravel, react-router, remix, astro, tanstack, tanstack-router, and manual. That list is broader than the examples shown in the supplied snippets, but it confirms the section’s role as a framework chooser. The overview page also includes a Choose Your Framework area and calls out Laravel separately, instructing readers to start with the Laravel project creation flow before using shadcn/create or shadcn init. Treat the index as the decision point, then move to the framework page that matches the application.
Sources: apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/meta.json
Astro demonstrates the most complete framework-specific flow in the supplied evidence. The guide repeats the three-choice structure from the overview, then shows create, CLI, and existing-project paths. After initialization, it adds the Card component and imports Card, CardContent, CardDescription, CardHeader, and CardTitle into an Astro page. It also documents the monorepo variation: run the add command from apps/web or pass a workspace path, then import from the workspace UI package instead of the local components alias. This shows how installation choices affect later component imports.
Sources: apps/v4/content/docs/installation/astro.mdx
Laravel demonstrates a framework integration rather than a scaffold. The guide states that the shadcn CLI does not scaffold a new Laravel app, so readers begin with laravel new and choose the React starter kit. After that, both shadcn/create and the CLI configure shadcn/ui inside the Laravel app. The component add example installs Switch under resources/js/components/ui and imports it in a page under resources/js/pages. This tells Laravel users that their final file layout follows Laravel and Inertia conventions, even though the shadcn component workflow remains recognizable.
Sources: apps/v4/content/docs/installation/laravel.mdx
Command and Configuration Reference
Use these commands as landmarks, then follow the framework-specific page for exact placement and prompts:
- Create a supported framework project from the terminal:
npx shadcn@latest init -t [framework] - Create an Astro project directly:
npx shadcn@latest init -t astro - Create an Astro monorepo:
npx shadcn@latest init -t astro --monorepo - Add a component after setup:
npx shadcn@latest add cardornpx shadcn@latest add switch - Target an Astro monorepo workspace from the root:
npx shadcn@latest add card -c apps/web - Configure an existing Laravel app from its root:
npx shadcn@latest init
Sources: apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/astro.mdx, apps/v4/content/docs/installation/laravel.mdx
The most important configuration reference is alias alignment. Manual setup allows TypeScript path aliases or package imports, but the chosen roots must agree with components.json so generated code imports from the same locations the application can resolve. Gatsby reinforces this point by configuring both tsconfig paths and webpack aliases. Astro reinforces it from the other direction: a non-monorepo example imports from a local components alias, while a monorepo example imports from a workspace UI package. Installation is successful only when the CLI output, TypeScript resolution, bundler resolution, and project layout all point to the same component locations.
Sources: apps/v4/content/docs/installation/manual.mdx, apps/v4/content/docs/installation/gatsby.mdx, apps/v4/content/docs/installation/astro.mdx
Relevant Source Files
- apps/v4/content/docs/installation/index.mdx — Defines the installation landing page, the three setup choices, the generic CLI command shape, supported template names, Laravel caveat, existing-project guidance, and framework chooser.
- apps/v4/content/docs/installation/manual.mdx — Documents the shared manual setup primitives: Tailwind CSS, dependencies, alias options, package imports alignment, and global style configuration.
- apps/v4/content/docs/installation/astro.mdx — Shows a full framework guide using shadcn/create, CLI scaffolding, monorepo flags, component addition, and Astro import examples.
- apps/v4/content/docs/installation/gatsby.mdx — Provides a special-case Gatsby path for Tailwind CSS v3, including TypeScript paths, webpack aliases, initialization, and adding Button.
- apps/v4/content/docs/installation/laravel.mdx — Explains that Laravel apps are created with Laravel tooling first, then configured with shadcn/create or CLI, with Switch installation under Laravel resource paths.
- apps/v4/content/docs/installation/meta.json — Lists the installation section pages used by the docs navigation.
Next Steps
Start with the overview decision: new visual preset, terminal scaffold, or existing-project integration. Then open the framework page that matches the application, because the final import paths and file locations differ by framework and by monorepo choice. If the project does not match a supported scaffold, read the manual installation page and verify Tailwind, dependencies, aliases, package imports, components.json, and global CSS before adding components. After setup, continue to pages for components.json, package imports, theming, Tailwind v4, and the CLI command reference to understand how future component additions will be resolved and styled.