How to Add Shadcn/ui to an Existing Next.js Template

#react #typescript #nextjs #tailwindcss

Adding Shadcn/ui to an existing Next.js template takes about 15 minutes if your template uses Tailwind CSS. The main consideration is CSS variable naming - Shadcn uses its own token names that you need to map to your existing design system.

Shadcn/ui is the most popular way to add high-quality accessible components to a Next.js project. If you're working with an existing template that already has Tailwind CSS set up, adding Shadcn/ui is straightforward - with one important caveat around CSS variables.

Step 1: Initialize Shadcn/ui

npx shadcn@latest init

# The CLI will ask:
# - Which style? → Default (or New York for tighter spacing)
# - Which color? → Pick any - you'll override the tokens anyway
# - Use CSS variables? → Yes

The init command adds a components.json config file, updates your globals.css with Shadcn's CSS variables, and installs required dependencies.

Step 2: Map your tokens to Shadcn variables

Shadcn/ui uses specific CSS variable names (--background, --foreground, --primary, etc.). Map them to your existing tokens:

/* globals.css */

/* Your existing tokens (keep these) */
@theme {
  --color-background: #ffffff;
  --color-foreground: #0c0c0d;
  --color-primary:    #e5402a;
  --color-border:     #e8e8e4;
  --color-muted:      #f0f0ee;
}

/* Map Shadcn variables to your tokens */
:root {
  --background:   var(--color-background);
  --foreground:   var(--color-foreground);
  --primary:      var(--color-primary);
  --border:       var(--color-border);
  --muted:        var(--color-muted);
  --radius:       0rem;
}

.dark {
  --background:   #0c0c0d;
  --foreground:   #fcfcfa;
  --primary:      #e5402a;
  --border:       rgba(255,255,255,0.08);
  --muted:        rgba(255,255,255,0.05);
}

Step 3: Add components

# Add individual components as you need them
npx shadcn@latest add button
npx shadcn@latest add input
npx shadcn@latest add dialog
npx shadcn@latest add table

# Or add multiple at once
npx shadcn@latest add button input dialog

Each component is copied into components/ui/ as source code you own and can modify freely.

Step 4: Tailwind CSS v4 compatibility

If your template uses Tailwind v4, add Shadcn's radius variable support in globals.css:

@import "tailwindcss";

@theme {
  --radius-sm: calc(var(--radius) - 2px);
  --radius-md: var(--radius);
  --radius-lg: calc(var(--radius) + 2px);
}

Step 5: Verify dark mode

Shadcn/ui reads the .dark class on <html>. Make sure your theme toggle sets it there:

// Correct - Shadcn reads .dark on <html>
document.documentElement.classList.toggle("dark");

// Wrong - Shadcn won't pick this up
document.body.setAttribute("data-theme", "dark");

Frequently asked questions

Does Shadcn/ui work with Tailwind CSS v4?

Yes, with minor adjustments. Configure in CSS instead of tailwind.config.js, map CSS variables using @theme, and ensure globals.css imports tailwindcss before Shadcn's variable declarations.

Will Shadcn/ui break my existing template styles?

Only if there are CSS variable name conflicts. Keep your template's token names and map the Shadcn variable names to your tokens as shown above.

Originally published at thekitbase.app

DEV Community