Next.js + Tailwind v4 + shadcn/ui

Arma un proyecto Next.js 15 con Tailwind CSS v4 y shadcn/ui — la pila exacta usada por este cookbook. App Router, React 19, TypeScript strict mode, Tailwind configurado vía CSS (no JS), y componentes shadcn que posees y editas directamente en components/ui/.

Receta

Tarjeta de receta de referencia rápida — lista para copiar y pegar.

# 1. Crea la app Next.js con Tailwind v4 integrado
npx create-next-app@latest my-app \
  --typescript \
  --tailwind \
  --app \
  --no-src-dir \
  --import-alias "@/*"
 
cd my-app
 
# 2. Inicializa shadcn/ui — respuestas: estilo New York, base Zinc, variables CSS
npx shadcn@latest init
 
# 3. Agrega un par de componentes
npx shadcn@latest add button card

Cuándo usarlo: Cualquier producto real. Tailwind v4 te da iteración rápida y CSS pequeño; shadcn te da primitivos accesibles y editables sin el bloqueo de una librería de componentes.

Ejemplo funcional

Después de la receta tendrás esta estructura:

my-app/
├── app/
│   ├── globals.css          # Tailwind v4 + variables CSS de shadcn
│   ├── layout.tsx
│   └── page.tsx
├── components/
│   └── ui/
│       ├── button.tsx       # agregado por shadcn
│       └── card.tsx         # agregado por shadcn
├── lib/
│   └── utils.ts             # el helper cn
├── components.json          # configuración shadcn
├── next.config.ts
├── package.json
├── postcss.config.mjs
└── tsconfig.json

lib/utils.ts es el fusionador de nombres de clase en el que dependen los componentes de shadcn:

// lib/utils.ts
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
 
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

components.json le dice al CLI de shadcn dónde poner archivos y qué alias usar:

// components.json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "zinc",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "utils": "@/lib/utils",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}

Tailwind v4 se configura dentro de app/globals.css — ya no hay archivo tailwind.config.js:

/* app/globals.css (abreviado) */
@import "tailwindcss";
@custom-variant dark (&:is(.dark *));
 
:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --radius: 0.625rem;
}
 
.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
}
 
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --radius-lg: var(--radius);
}

Una página que usa los componentes instalados Button y Card — es un Server Component, no se necesita "use client":

// app/page.tsx
import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
 
export default function HomePage() {
  return (
    <main className="mx-auto max-w-md p-8">
      <Card>
        <CardHeader>
          <CardTitle>Bienvenido</CardTitle>
          <CardDescription>
            Next.js 15 + Tailwind v4 + shadcn/ui
          </CardDescription>
        </CardHeader>
        <CardContent>
          <p className="text-sm text-muted-foreground">
            Cada pieza aquí es código fuente editable que posees.
          </p>
        </CardContent>
        <CardFooter>
          <Button>Comenzar</Button>
        </CardFooter>
      </Card>
    </main>
  );
}

Análisis profundo

Cómo funciona

create-next-app --tailwind escribe en app/globals.css con @import "tailwindcss", agrega @tailwindcss/postcss a postcss.config.mjs, y agrega Tailwind v4 a package.json. No hay tailwind.config.js; Tailwind v4 lee la configuración desde CSS usando @theme, @custom-variant, y at-rules relacionadas.

npx shadcn@latest init inspecciona tu proyecto, confirma el framework (Next.js App Router), pregunta por un color base y estilo, luego escribe components.json, lib/utils.ts, y agrega variables CSS y un bloque @theme inline a app/globals.css. No instala una librería de componentes — cada npx shadcn add <nombre> obtiene el código fuente de ese componente del registro de shadcn y copia el .tsx sin procesar en components/ui/. Lo posees desde ese momento en adelante.

El helper cn() fusiona nombres de clase en dos capas: clsx maneja condicionales y arrays, luego twMerge deduplica clases Tailwind conflictivas (p.ej. px-2 gana sobre px-4 cuando ambas aparecen). Cada componente shadcn lo usa para la propiedad className para que puedas anular defaults sin guerras de especificidad.

Variaciones

• Color base: en el momento de init, elige slate, gray, zinc (por defecto en este cookbook), neutral, o stone. Puedes cambiarlo más tarde volviendo a ejecutar npx shadcn@latest init o editando manualmente las variables CSS.
• Dark mode con next-themes: npm install next-themes, envuelve <body> en un cliente ThemeProvider, y la variante de clase .dark de shadcn funciona directamente porque @custom-variant dark (&:is(.dark *)) ya está en globals.css.
• Temas personalizados: edita las variables CSS :root y .dark en globals.css; no se necesita paso de reconstrucción, Tailwind v4 las detecta.
• Iconos Lucide: npm install lucide-react, luego import \{ ArrowRight \} from "lucide-react". Los componentes shadcn usan Lucide internamente por lo que ya es una dependencia transitiva.
• Instala un componente específico: npx shadcn@latest add dialog form input select. Las dependencias (como primitivos de Radix) se instalan automáticamente.
• Monorepo: usa npx shadcn@latest init desde dentro de tu workspace de app, establece los alias de components.json para que coincidan con las rutas TS de tu workspace, y apunta tailwind.css al globals.css más cercano.

Notas de TypeScript

La firma de cn es cn(...inputs: ClassValue[]): string, donde ClassValue es la unión de clsx de string | number | boolean | undefined | null | ClassDictionary | ClassArray. Eso significa que puedes pasar objetos condicionales como cn("p-4", \{ "bg-primary": isActive \}) y TS no se quejará.

Los componentes personalizados tipo botón deben extender el tipo de propiedad nativa para que las refs, aria-*, y manejadores de eventos vengan gratis:

import * as React from "react";
import { cn } from "@/lib/utils";
 
type ButtonProps = React.ComponentPropsWithoutRef<"button"> & {
  variant?: "default" | "outline";
};
 
export function MyButton({ className, variant = "default", ...props }: ButtonProps) {
  return (
    <button
      className={cn(
        "rounded-md px-4 py-2",
        variant === "outline" && "border",
        className,
      )}
      {...props}
    />
  );
}

El propio Button de shadcn usa class-variance-authority (cva) y expone un tipo VariantProps<typeof buttonVariants> para que cada combinación de variante sea type-safe.

Trampas

1. shadcn pregunta sobre TypeScript y JavaScript por separado. Incluso si tu app Next es TypeScript, el prompt de init de shadcn preguntará de nuevo. Di sí, o escribirá archivos .jsx en un proyecto TS.
2. La configuración de Tailwind v4 vive en CSS, no en JS. Si una publicación de blog te dice que edites tailwind.config.js, eso es Tailwind v3. En v4 el archivo no existe; usa @theme dentro de app/globals.css.
3. Los alias de components.json deben coincidir con las rutas de tsconfig.json. Si cambias "@/*" en tsconfig.json pero no en components.json, los componentes shadcn recién agregados importarán desde una ruta que no se resuelve.
4. Estrategia de clase de dark mode vs media. shadcn por defecto usa dark mode basado en clases vía @custom-variant dark (&:is(.dark *)). Si quieres prefers-color-scheme, debes editar esa línea a @custom-variant dark (&:is(@media (prefers-color-scheme: dark))) — el default hará nada silenciosamente sin una clase .dark en un antecesor.
5. cn() no es opcional. Si la dejas y concatenas strings de clase con literales de plantilla, las clases Tailwind conflictivas ya no se fusionarán y los overrides de props perderán aleatoriamente.
6. @import "tailwindcss" debe ser la primera línea de globals.css. Poner variables CSS por encima de la importación rompe el ordenamiento de capas de Tailwind v4 y tus clases text-primary aparecerán sin estilo.
7. postcss.config.mjs debe usar @tailwindcss/postcss, no tailwindcss. Tailwind v4 movió el plugin de PostCSS a un paquete separado; el nombre de plugin antiguo lanza un error en tiempo de compilación.

Alternativas

FAQs

Revisión rápida de esta página — haz clic para expandir.

Relacionado

• Configuración básica de Next.js
• Banderas de CLI create-next-app