OpenWikishadcn-ui/ui

Manual Installation

Purpose and Scope

Manual installation is the path for an existing application when you are not starting from a generated shadcn template and do not want a framework guide to make every decision for you. The manual page says its job directly: add dependencies to your project manually, install Tailwind CSS, configure aliases, and add the shared global styles that components expect. This is most useful when your application already has a router, build system, source layout, or framework conventions that differ from the first-party templates. Sources: apps/v4/content/docs/installation/manual.mdx, apps/v4/content/docs/installation/index.mdx

The installation overview frames manual setup as part of a broader decision tree. New projects are steered toward shadcn/create, which builds a preset visually and generates a framework-specific setup command. The CLI can scaffold supported templates from the terminal. Existing projects, however, are expected to follow either a framework-specific existing-project section or the manual flow when no framework guide fits. That distinction matters because shadcn/ui is distributed as code you own: the installation work aligns your project so added components can import utilities, use Tailwind classes, and share theme variables. Sources: apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/meta.json

Relevant Source Files

  • apps/v4/content/docs/installation/manual.mdx - Defines the manual installation sequence: Tailwind CSS, package dependencies, alias choices, and the global CSS theme setup.
  • apps/v4/content/docs/installation/index.mdx - Explains the installation decision tree: shadcn/create for new projects, the CLI for scaffolding, and existing-project setup through framework guides.
  • apps/v4/content/docs/installation/astro.mdx - Shows how a framework guide adapts the same concepts for Astro, including create, CLI, existing project, component add commands, and import conventions.
  • apps/v4/content/docs/installation/gatsby.mdx - Provides an older framework-specific manual-style flow, including TypeScript paths, webpack aliases, CLI initialization, and component import usage.
  • apps/v4/content/docs/installation/laravel.mdx - Demonstrates that some frameworks require a host app first, then shadcn initialization and component imports in framework-specific source locations.
  • apps/v4/content/docs/installation/meta.json - Lists the installation pages and confirms manual installation is one of the documented installation options.

Core Primitives

Manual setup has four core primitives. First, Tailwind CSS is the styling engine, so the app must already process Tailwind directives before shadcn/ui components will render correctly. Second, dependency packages provide the reusable building blocks that components rely on: the CLI package, variant composition, class merging, icons, and animation utilities. Third, import aliases provide stable source paths so generated component code can import from predictable roots. Fourth, global CSS establishes the theme contract, including Tailwind imports, dark-mode variant behavior, theme token mappings, radius scales, sidebar tokens, and light and dark CSS variables. Sources: apps/v4/content/docs/installation/manual.mdx

Those primitives are intentionally independent. Tailwind can be installed according to the host framework’s own instructions, while aliases can be expressed either through TypeScript path mapping or through package import maps. The manual guide explicitly says the at-sign alias is a preference, not a requirement. If a project uses package import maps instead, the important rule is consistency: the alias roots in the import map must match the roots in the shadcn configuration. That is why the manual page points readers to the package imports guide for framework-specific package import setup. Sources: apps/v4/content/docs/installation/manual.mdx

Manual Setup Flow

Start by installing Tailwind CSS using the official Tailwind installation instructions for your project. The manual page does not replace framework-specific Tailwind setup because bundlers and frameworks wire CSS differently. Instead, it establishes that shadcn/ui components are styled with Tailwind and assumes your build can consume Tailwind’s CSS entrypoint. After Tailwind is present, install the dependency set shown by the manual guide. This gives the project the shadcn command, class variance utilities, class name helpers, Lucide icons, and animation CSS integration needed by generated components. Sources: apps/v4/content/docs/installation/manual.mdx

npm install shadcn class-variance-authority clsx tailwind-merge lucide-react tw-animate-css

Next, choose an alias strategy. The simplest documented option is a TypeScript configuration with a project base URL and an at-sign path that resolves to the project root. This is convenient for projects whose component imports look like at-sign slash components slash ui slash button or at-sign slash lib slash utils. The second documented option uses package import maps with hash-prefixed roots for components, library files, and hooks. That approach is useful when the runtime and tooling understand package imports and the project prefers explicit import-map roots over broad TypeScript path aliases. Sources: apps/v4/content/docs/installation/manual.mdx

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}
{
  "imports": {
    "#components/*": "./src/components/*.tsx",
    "#lib/*": "./src/lib/*.ts",
    "#hooks/*": "./src/hooks/*.ts"
  }
}

When using package imports, the manual guide also requires TypeScript settings that use bundler-style module resolution and resolve package import maps. This is a configuration handshake: package.json tells the JavaScript tooling what the hash-prefixed imports mean, and TypeScript needs to understand the same convention while editing and typechecking. The same root names must then be reflected in components.json so the shadcn tooling writes imports that your project can resolve. If those settings diverge, components may be generated successfully but fail during development because an import path points at a root the compiler or bundler does not know. Sources: apps/v4/content/docs/installation/manual.mdx

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "resolvePackageJsonImports": true
  }
}

Styles and Theme Contract

The global stylesheet is the largest part of the manual page because it is where the visual system becomes executable. The documented file imports Tailwind CSS, the animation helper CSS, and shadcn’s Tailwind CSS entry. It then defines a custom dark variant and an inline theme block that maps Tailwind color and radius names to CSS variables. This lets components use stable utility classes while the actual values remain customizable through variables such as background, foreground, primary, border, ring, chart colors, and sidebar-specific tokens. Sources: apps/v4/content/docs/installation/manual.mdx

The manual stylesheet also declares a root radius and a light color palette using OKLCH values. The snippet continues into the full theme variable set, and the page explicitly connects that setup to the theming documentation. In practice, this means manual installation is not just dependency wiring; it is the initial definition of the project’s design tokens. Once the variables exist, future component additions can assume the same semantic color names, radius scale, and dark-mode behavior as the official examples. Teams that already have a design system should map their existing values into these variables rather than editing each component independently. Sources: apps/v4/content/docs/installation/manual.mdx

@import "tailwindcss";
@import "tw-animate-css";
@import "shadcn/tailwind.css";
 
@custom-variant dark (&:is(.dark *));

Relationship to Framework Guides

The neighboring installation guides show when to prefer a framework-specific path over the generic manual page. Astro, for example, offers shadcn/create, CLI scaffolding, monorepo flags, component add commands, and Astro page imports. Its example imports a Card component into an Astro page and notes that monorepos use workspace imports and a shared globals file. Laravel begins outside the shadcn CLI because the CLI does not scaffold a Laravel app; the guide starts with the Laravel installer and React starter kit, then runs shadcn initialization from the Laravel root. Sources: apps/v4/content/docs/installation/astro.mdx, apps/v4/content/docs/installation/laravel.mdx

Gatsby illustrates a more manual framework-specific bridge. Its guide targets Gatsby with Tailwind CSS version three and recommends newer Tailwind version four frameworks for new projects. It creates a Gatsby project, selects TypeScript and Tailwind, edits TypeScript paths, adds webpack aliases in gatsby-node, runs the shadcn init command, and then adds a button. That sequence is a useful pattern for unsupported or unusual setups: make the host framework resolve aliases first, run shadcn initialization, add one small component, and verify both the import path and styling pipeline before scaling up. Sources: apps/v4/content/docs/installation/gatsby.mdx

Verification and Next Steps

After completing the manual flow, verify the setup with a small component rather than migrating an entire screen. The framework guides repeatedly use this pattern: run a shadcn add command, import the generated component from the configured alias, and render it in a page. If the import fails, revisit the alias configuration and components.json alignment. If the component renders without styles, revisit Tailwind installation and the global CSS import location. If colors or radius values look wrong, compare your global variables with the documented theme contract and then continue in the theming guide. Sources: apps/v4/content/docs/installation/manual.mdx, apps/v4/content/docs/installation/astro.mdx, apps/v4/content/docs/installation/gatsby.mdx

Use the installation overview to decide whether manual setup is still the right path. For new apps in supported frameworks, shadcn/create or the CLI can generate a correct starting point faster and reduce configuration drift. For existing apps, the manual page gives the portable minimum: Tailwind, dependencies, aliases, and global styles. Once those pieces are in place, the next practical pages are the package imports guide if you chose import maps, the theming guide if you need brand tokens, the CLI page for add and init behavior, and the monorepo page if components live in a shared workspace. Sources: apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/manual.mdx

Ask a question...