Instalación y configuración de Tailwind v4

Instalación de Tailwind CSS v4

Tailwind v4 simplifica su instalación respecto a la v3. Existen dos caminos principales según el bundler que uses: el plugin de Vite (recomendado para la mayoría de proyectos modernos) o el plugin de PostCSS (para proyectos con Webpack u otros bundlers).

Instalación con Vite (recomendado)

Si tu proyecto usa Angular con el builder esbuild/Vite, React + Vite, Vue + Vite o cualquier otro framework que use Vite como bundler, esta es la ruta más eficiente.

Paso 1: Instalar las dependencias

# Con npm
npm install tailwindcss @tailwindcss/vite

# Con bun (más rápido)
bun add tailwindcss @tailwindcss/vite

Paso 2: Configurar el plugin en Vite

Agrega el plugin de Tailwind a tu vite.config.ts:

import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';
import angular from '@analogjs/platform'; // o el plugin de tu framework

export default defineConfig({
  plugins: [
    tailwindcss(),
    angular(),
  ],
});

Paso 3: Importar Tailwind en tu CSS principal

En tu archivo CSS de entrada (por ejemplo src/styles.css en Angular o src/index.css en React/Vue), agrega:

@import "tailwindcss";

¡Eso es todo! No necesitas directivas @tailwind base, @tailwind components, @tailwind utilities como en v3. Una sola línea de importación lo hace todo.

Instalación con PostCSS

Para proyectos que usan Webpack, Parcel, o cualquier bundler diferente de Vite:

Paso 1: Instalar las dependencias

npm install tailwindcss @tailwindcss/postcss autoprefixer

Paso 2: Crear la configuración de PostCSS

Crea postcss.config.mjs en la raíz del proyecto:

export default {
  plugins: {
    '@tailwindcss/postcss': {},
    'autoprefixer': {},
  },
};

Paso 3: Importar en tu CSS principal

Igual que con Vite:

@import "tailwindcss";

Instalación en Angular

Angular 17+ usa esbuild como bundler por defecto, con soporte para Vite en el servidor de desarrollo. La configuración es ligeramente diferente:

Paso 1: Instalar dependencias

ng new mi-proyecto --style=css
cd mi-proyecto
bun add tailwindcss @tailwindcss/vite

Paso 2: Ajustar `angular.json`

Para Angular con el builder moderno (application builder), Tailwind v4 con PostCSS funciona sin necesidad de configuración extra de Vite, pero si prefieres el plugin de Vite, ajusta el vite.config.ts si existe.

La opción más común en Angular es usar el enfoque PostCSS:

bun add @tailwindcss/postcss

Y en postcss.config.mjs:

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

Paso 3: Agregar importación en styles.css

En src/styles.css:

@import "tailwindcss";

Verifica que src/styles.css esté referenciado en el array styles de angular.json:

"styles": [
  "src/styles.css"
]

La directiva `@theme`: configuración CSS-first

La directiva @theme es el corazón de la configuración en Tailwind v4. Reemplaza completamente al objeto theme.extend de tailwind.config.js. Aquí defines tus tokens de diseño como variables CSS, y Tailwind genera automáticamente las utilidades correspondientes.

Colores personalizados

@import "tailwindcss";

@theme {
  /* Tailwind generará: text-brand, bg-brand, border-brand, etc. */
  --color-brand: #ff530f;
  --color-brand-50: #fff3ee;
  --color-brand-100: #ffe6d8;
  --color-brand-500: #ff530f;
  --color-brand-900: #7a1f00;
}

Con esto, puedes usar bg-brand-500, text-brand-50, border-brand-900 igual que usarías bg-blue-500.

Fuentes

@theme {
  --font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
  --font-heading: 'Playfair Display', Georgia, serif;
  --font-code: 'JetBrains Mono', 'Fira Code', monospace;
}

Genera utilidades: font-sans, font-heading, font-code.

Espaciado y tamaños

@theme {
  /* Extiende la escala de espaciado */
  --spacing-18: 4.5rem;   /* p-18, m-18, gap-18 */
  --spacing-128: 32rem;   /* w-128, h-128 */
}

Breakpoints personalizados

@theme {
  --breakpoint-xs: 480px;    /* xs:hidden, xs:flex, etc. */
  --breakpoint-3xl: 1920px;  /* 3xl:grid-cols-6 */
}

Sombras y bordes

@theme {
  --shadow-card: 0 4px 24px 0 rgba(0,0,0,0.08);
  --shadow-modal: 0 20px 60px 0 rgba(0,0,0,0.3);
  --radius-card: 0.75rem;
  --radius-button: 0.5rem;
}

La directiva `@source`

En v4, Tailwind detecta automáticamente los archivos a escanear para encontrar clases usadas. Busca en archivos .html, .js, .ts, .jsx, .tsx, .vue, .svelte, etc., en el directorio relativo al CSS de entrada.

Sin embargo, a veces necesitas indicarle fuentes adicionales:

@import "tailwindcss";

/* Escanear componentes de una librería en node_modules */
@source "../node_modules/@mi-empresa/design-system/dist/**/*.js";

/* Escanear archivos PHP en un proyecto Laravel */
@source "../resources/views/**/*.php";

Desactivar la detección automática

Si necesitas control total sobre qué se escanea:

@import "tailwindcss" source(none);

@source "./src/**/*.{html,ts,tsx}";
@source "./public/**/*.html";

Integración con React y Next.js

React + Vite

npm create vite@latest mi-app -- --template react-ts
cd mi-app
npm install tailwindcss @tailwindcss/vite

vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [react(), tailwindcss()],
});

src/index.css:

@import "tailwindcss";

Next.js

Next.js 15+ incluye soporte integrado para Tailwind v4:

npx create-next-app@latest mi-app --tailwind

Si lo agregas manualmente:

npm install tailwindcss @tailwindcss/postcss

postcss.config.mjs:

export default {
  plugins: { '@tailwindcss/postcss': {} }
};

Verificar que todo funciona

Para confirmar que Tailwind está funcionando, agrega una clase en tu componente raíz:

<h1 class="text-4xl font-bold text-blue-600 p-8">
  ¡Tailwind v4 funciona!
</h1>

Si ves el texto en azul, grande y con padding, la instalación es correcta.

Resumen de comandos según stack

Con la instalación lista, ya puedes comenzar a escribir utilidades de Tailwind. En la siguiente lección explorarás las utilidades más esenciales del framework.