Diferencias entre Tailwind CSS v3 y v4 que afectan este curso

El curso del profesor Oscar Barajas usa la versión 3.4.17 de Tailwind CSS, mientras que la versión actual de la documentación oficial es la v4. Si sigues las lecciones con una instalación nueva, lo más probable es que instales la v4 y notes que algunas cosas del curso no coinciden: ya no existe tailwind.config.js por defecto, las directivas @tailwind desaparecieron y varias clases cambiaron de nombre.

Este tutorial resume las diferencias principales, con ejemplos de antes y después, y señala en qué lecciones del curso las vas a notar.

Qué versión conviene usar

Tienes dos opciones, y ambas son válidas:

• Seguir el curso al pie de la letra con la v3.4.17. Es lo más sencillo si quieres que todo coincida con los videos.
• Usar la v4 y adaptar lo que cambie. Es lo recomendable si quieres aprender lo que se usa hoy en proyectos nuevos. Para eso sirve esta guía.

Para instalar exactamente la versión del curso:

npm install -D tailwindcss@3.4.17
npx tailwindcss init

Para instalar la versión actual (v4) con la CLI:

npm install tailwindcss @tailwindcss/cli

Un dato importante antes de decidir: la v4 está diseñada para navegadores modernos (Safari 16.4 o superior, Chrome 111 o superior y Firefox 128 o superior). Si necesitas soportar navegadores más antiguos, la documentación oficial recomienda quedarte en la v3.4.

Resumen rápido

• La configuración pasa de un archivo JavaScript (tailwind.config.js) al propio CSS, con la directiva @theme.
• Las tres directivas @tailwind base, @tailwind components y @tailwind utilities se reemplazan por una sola línea: @import "tailwindcss".
• La CLI vive ahora en un paquete aparte: @tailwindcss/cli.
• Ya no hace falta indicar en content dónde están tus archivos, porque Tailwind detecta las clases automáticamente.
• Varias clases cambiaron de nombre (shadow, rounded, blur, ring, outline-none, entre otras).
• Los plugins se cargan desde el CSS con @plugin.
• Para Astro, la integración recomendada ahora es el plugin de Vite @tailwindcss/vite.

1. Importar Tailwind en tu CSS

Esto lo vas a notar desde la lección 3 del curso, cuando creas el archivo CSS de entrada.

En la v3 se usaban tres directivas:

@tailwind base;
@tailwind components;
@tailwind utilities;

En la v4 se importa con una sola línea de CSS normal:

@import "tailwindcss";

2. El comando de la CLI

Esto afecta a las lecciones 3 y 4 (configuración con Node y modo watch).

En la v3 el comando se ejecutaba con el paquete tailwindcss:

npx tailwindcss -i ./src/input.css -o ./src/output.css --watch

En la v4 la CLI está en su propio paquete:

npx @tailwindcss/cli -i ./src/input.css -o ./src/output.css --watch

Los parámetros -i (entrada), -o (salida) y --watch funcionan igual. Si quieres ver cómo dejar esto listo con los scripts dev y build y cómo desplegarlo, revisa el tutorial sobre cómo usar Tailwind CLI en lugar del CDN.

3. El CDN

Esto afecta a la lección 2 (primeros pasos sin instalar nada).

El curso usa el CDN de la v3. Para la v4, el CDN oficial de prueba es el paquete @tailwindcss/browser:

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

En ambos casos el CDN es solo para pruebas y prototipos. Para un proyecto real, la documentación recomienda instalar Tailwind con la CLI, Vite o PostCSS.

4. La configuración: de tailwind.config.js a @theme

Esto afecta a las lecciones donde personalizas colores, fuentes o breakpoints (especialmente la 15).

En la v3, la personalización vivía en un archivo JavaScript:

// tailwind.config.js
module.exports = {
  content: ["./**/*.html"],
  theme: {
    extend: {
      colors: {
        brand: "#3b82f6",
      },
    },
  },
};

En la v4 se hace directamente en el CSS con @theme:

@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
}

Con eso ya puedes usar clases como bg-brand o text-brand. Cada valor del tema se genera además como una variable CSS, así que también puedes usar var(--color-brand) en tu propio CSS.

Algunos detalles de esta migración:

• El archivo tailwind.config.js sigue siendo compatible, pero ya no se detecta automáticamente. Si lo necesitas, hay que cargarlo de forma explícita con @config "../../tailwind.config.js";.
• La opción content ya no es necesaria porque las clases se detectan solas.
• Las opciones corePlugins, safelist y separator del config de JavaScript no se soportan en la v4.
• La función theme() del CSS sigue existiendo, pero se recomienda usar variables CSS. Por ejemplo, en lugar de theme(colors.red.500) se usa var(--color-red-500).

5. Clases que cambiaron de nombre

Esto afecta sobre todo a las lecciones 7, 8 y 9 (tipografía, cajas, colores) y a todo lo que lleve sombras, bordes redondeados o bordes.

La v4 renombró algunas utilidades para que cada una tenga un valor con nombre. Las versiones sin sufijo todavía funcionan por compatibilidad, pero se ven distintas, así que conviene actualizarlas:

<!-- v3 -->
<div class="shadow-sm rounded blur-sm"></div>
<div class="shadow rounded-sm blur"></div>

<!-- v4 -->
<div class="shadow-xs rounded-xs blur-xs"></div>
<div class="shadow-sm rounded-sm blur-sm"></div>

La regla general es que lo que antes era sm ahora es xs, y lo que antes no tenía sufijo ahora es sm. Esto aplica a shadow, drop-shadow, blur, backdrop-blur y rounded.

Otros cambios de nombre importantes:

<!-- v3 -->
<input class="focus:outline-none focus:ring" />

<!-- v4 -->
<input class="focus:outline-hidden focus:ring-3" />

• outline-none pasa a llamarse outline-hidden. En la v4, outline-none existe pero realmente quita el contorno.
• ring pasa de 3px a 1px de grosor. Para conseguir el mismo efecto que en la v3, usa ring-3.
• flex-shrink-* y flex-grow-* pasan a shrink-* y grow-*. Esto lo vas a ver en la lección 12 (Flexbox).
• overflow-ellipsis pasa a text-ellipsis.

6. Utilidades de opacidad eliminadas

Esto afecta a la lección 9 (colores).

En la v3 existían utilidades separadas como bg-opacity-50. En la v4 fueron eliminadas y se usa el modificador con barra:

<!-- v3 -->
<div class="bg-black bg-opacity-50"></div>

<!-- v4 -->
<div class="bg-black/50"></div>

El modificador con barra también funciona en la v3, así que puedes empezar a usarlo desde ahora y tu código sirve en ambas versiones. Lo mismo aplica a text-opacity-*, border-opacity-*, divide-opacity-*, ring-opacity-* y placeholder-opacity-*.

7. Colores por defecto de bordes y degradados

Esto afecta a las lecciones 8 y 9.

Color del borde. En la v3, border usaba gray-200 por defecto. En la v4 usa currentColor, es decir, el color del texto. Si en el curso ves que un borde sale gris claro y en tu proyecto sale negro, es por esto. La solución es indicar siempre el color:

<div class="border border-gray-200 p-4">Contenido</div>

Degradados. En la documentación de la v4 los degradados lineales aparecen como bg-linear-to-r en lugar de bg-gradient-to-r:

<!-- v3 -->
<div class="bg-gradient-to-r from-red-500 to-yellow-400"></div>

<!-- v4 -->
<div class="bg-linear-to-r from-red-500 to-yellow-400"></div>

Además, en la v4 si sobrescribes solo una parte del degradado con una variante (por ejemplo dark:from-blue-500), las demás paradas se conservan, mientras que en la v3 se reiniciaba todo el degradado.

8. Breakpoints y el contenedor

Esto afecta a las lecciones 10 y 11 (diseño responsivo, container y max-width).

Los breakpoints básicos (sm, md, lg, xl, 2xl) se usan igual en ambas versiones:

<div class="p-4 md:p-8 lg:p-12"></div>

Lo que cambia es cómo se personalizan. En la v3 se hacía en theme.screens; en la v4 se define una variable en @theme:

@theme {
  --breakpoint-3xl: 120rem;
}

Con eso ya puedes usar 3xl: como prefijo en tus clases.

La clase container también cambió. En la v3 podías configurar center y padding en el archivo de configuración. En la v4 esas opciones ya no existen, y se personaliza con @utility:

@utility container {
  margin-inline: auto;
  padding-inline: 2rem;
}

Esto es lo que más vas a notar en la lección 11, donde se usa container junto con max-width.

9. Separación entre elementos y Flexbox

Esto afecta a la lección 12 (Flexbox) y 13 (Grid vs Flexbox).

Las clases space-x-* y space-y-* cambiaron internamente su selector por temas de rendimiento. En la mayoría de casos no notarás diferencia, pero si ves espaciados distintos, la documentación recomienda migrar a flex o grid con gap:

<!-- Con space-y -->
<div class="space-y-4">
  <p>Uno</p>
  <p>Dos</p>
</div>

<!-- Con flex y gap -->
<div class="flex flex-col gap-4">
  <p>Uno</p>
  <p>Dos</p>
</div>

Otro cambio en esta zona: los valores arbitrarios de grid-cols-* ya no convierten las comas en espacios, y se usan guiones bajos:

<!-- v3 -->
<div class="grid-cols-[max-content,auto]"></div>

<!-- v4 -->
<div class="grid-cols-[max-content_auto]"></div>

10. Plugins: forms, aspect-ratio y typography

Esto afecta a las lecciones 16 y 17.

En la v3, los plugins se registraban en el archivo de configuración:

// tailwind.config.js
module.exports = {
  plugins: [
    require("@tailwindcss/forms"),
    require("@tailwindcss/typography"),
  ],
};

En la v4 se cargan desde el CSS con @plugin:

@import "tailwindcss";
@plugin "@tailwindcss/forms";
@plugin "@tailwindcss/typography";

La instalación del paquete es la misma en ambas versiones:

npm install -D @tailwindcss/forms @tailwindcss/typography

Si dejas una línea @plugin sin haber instalado el paquete, Tailwind mostrará un error indicando que no puede resolverlo.

Una nota sobre los selectores apilados: en la v4 las variantes encadenadas se aplican de izquierda a derecha, y en la v3 se aplicaban de derecha a izquierda. Esto puede afectar combinaciones como prose-headings con otras variantes.

11. Astro y Next.js

Esto afecta a las lecciones 14, 15, 18 y 19.

Astro. En la v3, la forma de integrar Tailwind era npx astro add tailwind, que instalaba la integración @astrojs/tailwind. Esa integración está deprecada para la v4. Desde Astro 5.2, la forma recomendada es el plugin de Vite de Tailwind. La configuración queda así:

npm install tailwindcss @tailwindcss/vite

// astro.config.mjs
import { defineConfig } from "astro/config";
import tailwindcss from "@tailwindcss/vite";

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

Luego creas un archivo de estilos global, por ejemplo src/styles/global.css, con @import "tailwindcss"; y lo importas en tu layout.

Next.js y otros proyectos con PostCSS. En la v3, el paquete tailwindcss era directamente el plugin de PostCSS. En la v4 el plugin está en un paquete separado, @tailwindcss/postcss. Además, ya no hace falta postcss-import ni autoprefixer:

// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

@apply en componentes de Astro, Vue o Svelte. En la v4, las hojas de estilo que se procesan por separado (como un bloque <style> dentro de un componente) no tienen acceso a las variables del tema ni a las utilidades personalizadas definidas en otro archivo. Para usarlas, se importa la referencia con @reference:

@reference "../styles/global.css";

h1 {
  @apply text-2xl font-bold;
}

Además, la v4 no está pensada para usarse con preprocesadores como Sass, Less o Stylus.

12. Otros cambios menores

• Modificador important. En la v3 se escribía al inicio (!flex). En la v4 se escribe al final (flex!). La forma antigua sigue funcionando pero está deprecada.
• Variables CSS en valores arbitrarios. En la v3 se usaba bg-[--mi-color]. En la v4 se usan paréntesis: bg-(--mi-color).
• Hover en pantallas táctiles. En la v4, la variante hover solo se aplica en dispositivos que soportan hover real.
• Botones. Con los estilos base de la v4, los botones usan el cursor por defecto en lugar de pointer. Si quieres el comportamiento anterior, agrega en tu CSS: button:not(:disabled) { cursor: pointer; } dentro de @layer base.
• Color del placeholder. Ahora usa el color del texto actual al 50% de opacidad, en lugar de gray-400.
• Prefijos. Ahora se escriben como una variante al inicio: tw:flex en lugar de tw-flex.

Herramienta de migración automática

Si tienes un proyecto en la v3 y quieres pasarlo a la v4, Tailwind ofrece una herramienta oficial que hace casi todo el trabajo: actualiza dependencias, migra el archivo de configuración a CSS y corrige las clases renombradas en tus plantillas.

npx @tailwindcss/upgrade

Requiere Node.js 20 o superior. La documentación recomienda ejecutarla en una rama nueva de Git y revisar los cambios antes de aceptarlos.

Cómo saber qué versión tienes

Si algo del curso no te funciona, comprueba primero tu versión:

npm list tailwindcss

Y en tu CSS, fíjate en la primera línea: si ves @tailwind base; estás en la v3, y si ves @import "tailwindcss"; estás en la v4.

Documentación oficial

• Guía oficial de actualización de v3 a v4
• Instalación de Tailwind CSS (v4)
• Variables de tema con @theme
• Directivas y funciones: @utility, @plugin, @config, @reference
• Detección de clases en archivos fuente
• Compatibilidad, CSS modules y preprocesadores
• Guía oficial de instalación en Astro
• Anuncio de Astro 5.2 con soporte para Tailwind 4
• Documentación de la v3.4 (la del curso)

Mi configuración

Puedes ver cómo quedó mi proyecto con la versión 4.3.5 en mi repositorio de GitHub: joedudev/curso-tailwind-platzi.

Si tienes dudas o encuentras otra diferencia entre versiones que afecte al curso, puedes dejarla en los comentarios de este tutorial.