Next.js Installation

Purpose and Scope

Use this page when you want to start a Next.js project with shadcn/ui or add shadcn/ui to a Next.js app that already exists. The first-party Next.js guide is organized around three starting points: building a visual preset with shadcn/create, scaffolding from the terminal with the CLI, and configuring an existing project manually. That structure matters because shadcn/ui is not a single opaque package install. It writes component source into your application, then expects your import aliases, styling entrypoints, and workspace location to match the project shape you chose. Sources: apps/v4/content/docs/installation/next.mdx, apps/v4/content/docs/installation/index.mdx

The recommended path for new projects is shadcn/create. The installation overview describes shadcn/create as the visual setup flow that generates the right framework command, and the Next.js page narrows that flow to a Next.js preset builder. In practice, this means you choose style, colors, fonts, icons, and other preset options before running a generated command. That generated command uses the shadcn CLI, but it carries the preset code and the Next.js template option so the terminal step reproduces the choices you made visually. Sources: apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/next.mdx

Relevant Source Files

• apps/v4/content/docs/installation/next.mdx - The primary Next.js installation guide, including shadcn/create, direct CLI scaffolding, component installation, monorepo command variants, and sample Card imports for a Next.js app page.
• apps/v4/content/docs/installation/index.mdx - The installation landing page that explains the three setup modes and lists Next.js among the supported framework templates.
• apps/v4/content/docs/installation/manual.mdx - The framework-independent manual setup reference for Tailwind CSS, dependencies, import aliases, package imports, and global styles.
• apps/v4/content/docs/installation/astro.mdx - A neighboring framework guide that mirrors the create and CLI flow, useful for confirming that monorepo workspace commands and component-add conventions are shared across templates.
• apps/v4/content/docs/installation/gatsby.mdx - A legacy-oriented installation guide that shows the manual alias and Tailwind configuration concerns readers may encounter outside the primary supported template flow.
• apps/v4/content/docs/installation/laravel.mdx - A framework guide that clarifies the difference between scaffolding a framework app and running shadcn init inside a pre-existing framework project.

Setup Paths

For a brand-new Next.js application, open shadcn/create with the Next.js template selected, build the preset visually, click Create Project, choose a package manager, and copy the generated command. The documented command shape is npx shadcn@latest init --preset [CODE] --template next, and the exact command may include options such as --base, --monorepo, or --rtl. Treat those flags as part of the project contract. They determine whether the generated app uses the base component family, a workspace layout, or right-to-left support from the beginning. Sources: apps/v4/content/docs/installation/next.mdx

If you prefer a terminal-first setup, run the CLI with the Next.js template flag. The documented command is npx shadcn@latest init -t next. The CLI then prompts for configuration choices such as base, preset, monorepo, and more. For a workspace layout, the Next.js page calls out npx shadcn@latest init -t next --monorepo, which makes the monorepo decision explicit instead of leaving it to later refactoring. The installation landing page uses the same generic pattern, npx shadcn@latest init -t [framework], and lists next as a supported template. Sources: apps/v4/content/docs/installation/next.mdx, apps/v4/content/docs/installation/index.mdx

For an existing Next.js project, follow the existing-project branch in the Next.js guide and use the manual installation reference as the underlying checklist. The manual page starts with Tailwind CSS, then installs shadcn-related dependencies, configures import aliases, and adds global styles. This is the path where project-specific details matter most: an existing app may already have a source directory, a custom alias, or a different styles file. The goal is not to imitate a generated template exactly, but to make the app satisfy the same assumptions that generated components rely on. Sources: apps/v4/content/docs/installation/next.mdx, apps/v4/content/docs/installation/manual.mdx

Commands and Import Conventions

After initialization, the guide uses the Card component as the first component-add example. In a standard Next.js app, run the add command from the project root, then import the generated component from the application alias. The example updates the app page and imports Card primitives from the components directory. This demonstrates the central shadcn/ui workflow: components are added into your codebase, composed in React, and then edited as local source when your design system needs changes. The CLI is therefore both an installer and a source generator, not merely a dependency manager. Sources: apps/v4/content/docs/installation/next.mdx

npx shadcn@latest init -t next
npx shadcn@latest add card

import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
 
export default function Home() {
  return (
    <Card className="max-w-sm">
      <CardHeader>
        <CardTitle>Project Overview</CardTitle>
        <CardDescription>
          Track progress and recent activity for your Next.js app.
        </CardDescription>
      </CardHeader>
      <CardContent>
        Your design system is ready. Start building your next component.
      </CardContent>
    </Card>
  )
}

Monorepo projects use the same component workflow, but the command location and import path change. The Next.js guide says to run the add command from apps/web or pass -c apps/web from the repository root. It also says that in a monorepo you update apps/web/app/page.tsx and import from @workspace/ui/components/card instead of the app-local alias. This distinction prevents a common mistake: adding files to the wrong workspace or importing from an alias that only exists inside a generated single-app template. Sources: apps/v4/content/docs/installation/next.mdx, apps/v4/content/docs/installation/astro.mdx

npx shadcn@latest add card
npx shadcn@latest add card -c apps/web

import { Card } from "@workspace/ui/components/card"

Core Primitives

The main primitives to understand are the CLI, the preset, the template, generated component files, aliases, and global styles. The CLI command initializes configuration and adds registry components. A preset captures visual and structural choices from shadcn/create. The template tells the CLI which framework layout to scaffold, with Next.js selected by next. Generated component files are the React source you own after installation. Aliases make imports such as @/components/ui/card resolve correctly, while global styles connect Tailwind CSS, animations, theme variables, and shadcn styling support. Sources: apps/v4/content/docs/installation/next.mdx, apps/v4/content/docs/installation/manual.mdx

Manual setup exposes the configuration beneath the generated Next.js path. The manual guide installs dependencies including shadcn, class-variance-authority, clsx, tailwind-merge, lucide-react, and tw-animate-css. It also offers two alias strategies: TypeScript paths using an @/* mapping, or package imports using roots such as #components/*, #lib/*, and #hooks/*. If you choose package imports, the manual page warns to keep matching alias roots in components.json. That alignment is important because generated components and CLI configuration must agree on where files live. Sources: apps/v4/content/docs/installation/manual.mdx

System-to-Code Mapping

Edge Cases and Framework Boundaries

The neighboring installation guides help define what is special about the Next.js flow and what is shared across frameworks. Astro mirrors the same create, CLI, add, and monorepo patterns, but its example imports into an Astro page and mentions a layout that already imports workspace global CSS. Laravel is different because the CLI does not scaffold the Laravel app; readers first create the Laravel project, then run shadcn initialization inside it. Gatsby is marked as a Tailwind CSS v3 guide for older projects. These contrasts reinforce that Next.js belongs to the first-class template path, while manual configuration remains available when a project falls outside the generated shape. Sources: apps/v4/content/docs/installation/astro.mdx, apps/v4/content/docs/installation/laravel.mdx, apps/v4/content/docs/installation/gatsby.mdx

When something goes wrong in a Next.js setup, inspect the assumptions in the same order the docs present them. First, verify that the project was initialized with the intended template and monorepo choice. Next, confirm that you are running component-add commands from the correct directory or passing the correct workspace configuration. Then check that imports match the project shape: single-app imports use the configured application alias, while monorepo imports come from the shared workspace package. Finally, compare your Tailwind, dependency, alias, and global style setup with the manual installation checklist. Sources: apps/v4/content/docs/installation/next.mdx, apps/v4/content/docs/installation/manual.mdx

Next Steps

After the first Card renders, continue by adding the components you actually need and reading the configuration pages that explain the generated files. The CLI page is the natural next stop for command details beyond init and add. The components.json page explains how aliases, React Server Components, TSX, Tailwind, and package import settings are recorded for future generation. If you selected a workspace layout, read the monorepo guide before adding many components so shared UI imports and app-local code stay consistent. For styling changes, move to theming, dark mode, and Tailwind v4 guidance.