Módulo 01 · 8 min de lectura

Instalación y configuración

La guía oficial para instalar Tailwind CSS v4 con CLI o Vite, entender cuándo elegir cada flujo y evitar errores comunes al empezar.

#instalación #tailwind v4 #vite #cli #cdn

¿CLI o Vite?

Tailwind CSS v4 se puede integrar de dos maneras recomendadas cuando trabajas en un proyecto real: con la CLI oficial o con el plugin oficial de Vite. La diferencia no es cuál es “mejor”, sino cuál encaja con tu stack actual.

  • CLI: ideal para HTML plano, proyectos pequeños o cualquier entorno que no use Vite.
  • Vite: la mejor opción si ya trabajas con React, Vue, Svelte, Astro o cualquier flujo moderno basado en Vite.
  • CDN: útil para demos rápidas, pero no para aprender el flujo real ni para publicar un proyecto serio.

En este curso

Verás los tres enfoques, pero empezamos por la CLI porque es la forma más directa de entender cómo Tailwind analiza tus archivos y genera CSS sin que un bundler oculte el proceso.

¿Por qué no empezar con CDN?

El Play CDN es cómodo para una prueba rápida, pero no representa el flujo real de trabajo de Tailwind v4.

Con CDN:

  • cargas muchísimo CSS que probablemente no vas a usar;
  • no practicas el proceso de compilación real;
  • no entiendes cómo se genera el CSS final a partir de tus clases;
  • pierdes el beneficio principal de Tailwind v4: generar solo lo que el proyecto necesita.

Si solo quieres experimentar unos minutos, puede servirte. Si quieres aprender bien o construir algo que sí vas a publicar, usa CLI o Vite.

Puedes probar utilidades sueltas en el Playground oficial de Tailwind, que suele ser mejor opción que pegar el CDN manualmente.

Cuándo elegir CLI y cuándo elegir Vite

La decisión se resume en una sola pregunta: ¿tu proyecto ya usa Vite?

  • Si la respuesta es no, usa la CLI.
  • Si la respuesta es sí, usa el plugin oficial de Vite.

Regla rápida

CLI para entender y arrancar rápido. Vite para integrarte a un entorno frontend moderno con recarga en caliente y un pipeline más completo.

Instalación oficial con Tailwind CLI

La CLI es la forma más sencilla de instalar Tailwind CSS v4 en un proyecto desde cero.

1. Inicializa tu proyecto con npm

Necesitas tener Node.js instalado. Si el proyecto arranca desde cero, primero genera tu package.json:

terminal
npm init -y

Ese comando prepara la base para instalar dependencias y registrar scripts.

2. Instala Tailwind y la CLI

Luego ejecuta:

terminal
npm install tailwindcss @tailwindcss/cli

3. Crea tu archivo CSS de entrada

Ahora crea un archivo CSS donde importarás Tailwind:

src/input.css
@import "tailwindcss";

Esa línea le dice a Tailwind que cargue su sistema de estilos dentro de ese archivo.

4. Ejecuta el proceso de compilación

Después necesitas compilar el archivo de entrada hacia un CSS de salida:

terminal
npx @tailwindcss/cli -i ./src/input.css -o ./src/output.css --watch
  • npx @tailwindcss/cli: lanza la CLI oficial de Tailwind.
  • -i ./src/input.css: define el archivo CSS de entrada donde está @import "tailwindcss";.
  • -o ./src/output.css: indica dónde se escribirá el CSS generado.
  • --watch: mantiene el proceso observando cambios para regenerar estilos automáticamente.

5. Enlaza el CSS compilado en tu HTML

Ahora conecta el archivo generado con tu HTML:

src/index.html
<!doctype html>
<html lang="es">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link href="./output.css" rel="stylesheet" />
<title>Proyecto Tailwind CLI</title>
</head>
<body>
<h1 class="text-3xl font-bold underline">
  ¡Suscríbete a mi canal de YouTube!
</h1>
</body>
</html>

Truco para ahorrar tiempo

Si no quieres escribir el comando de compilación completo cada vez, puedes guardarlo como script dentro de tu package.json y ejecutarlo con npm run tailDev.

package.json
{
"scripts": {
  "tailDev": "npx @tailwindcss/cli -i ./src/input.css -o ./src/output.css --watch"
}
}
terminal
npm run tailDev

6. Qué acaba de pasar

Tailwind escanea tus archivos en busca de clases de utilidad como text-3xl, font-bold o underline.

Solo las clases que encuentra se convierten en CSS real y se escriben dentro de ./src/output.css. Eso hace que el resultado sea más ligero y más mantenible que cargar una hoja enorme con todo el framework completo.

La idea importante

Tailwind no funciona por magia: detecta clases de utilidad en tus archivos, genera solo ese CSS y luego tu HTML consume el archivo resultante como cualquier hoja de estilos normal.

Instalación con Vite

Si tu proyecto ya usa Vite, la integración recomendada es @tailwindcss/vite.

1. Crea un proyecto de Vite

terminal
npm create vite@latest my-project

2. Instala Tailwind y el plugin oficial

terminal
npm install tailwindcss @tailwindcss/vite
  • tailwindcss: el motor principal de Tailwind.
  • @tailwindcss/vite: el plugin que integra Tailwind directamente con Vite.

3. Registra el plugin en vite.config.ts

vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'


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

4. Crea tu archivo CSS de entrada

src/input.css
@import "tailwindcss";

5. Importa ese CSS en tu entrada principal

Para que los estilos realmente apliquen, importa el archivo en main.js o main.ts:

src/main.js
import './input.css'

6. Corre el servidor

Levanta el entorno de desarrollo:

terminal
npm run dev

Vite detectará cambios y Tailwind empezará a generar estilos en tiempo real.

Verificación rápida

Una vez conectado todo, prueba este componente:

index.html
<article class="space-y-4 bg-blue-600 p-8 text-white">
<h1 class="text-center text-3xl font-bold">
  ¡Tu primer componente con Tailwind!
</h1>
<a class="mx-auto block max-w-80 rounded-3xl bg-white py-4 text-center text-blue-600">
  Accede al curso completo de Tailwind
</a>
</article>

Si el bloque ya tiene color, padding, tipografía y bordes redondeados, la instalación está funcionando correctamente.

Documentación oficial

Si quieres continuar desde la fuente oficial, revisa la guía de instalación de Tailwind: