Cómo usar Tailwind CSS con la CLI en lugar del CDN

El curso enseña a usar Tailwind mediante el CDN, que es la forma más rápida de empezar porque no hay que instalar nada. En este tutorial te muestro una alternativa: instalar Tailwind con la CLI y compilar tu propio archivo CSS.

Aclaración importante: esto es una preferencia personal. Lo hago así porque quiero usar la extensión Tailwind CSS IntelliSense de VS Code, que ofrece autocompletado, resaltado de sintaxis y detección de errores en las clases. Para activarse, esta extensión necesita encontrar un archivo .css que importe Tailwind (por ejemplo, con @import "tailwindcss"). Con el CDN no existe ese archivo, así que la extensión no tiene nada que detectar. Si no te interesa la extensión, puedes seguir el curso con el CDN sin ningún problema.

Además, en lo personal creo que conviene practicar con la misma configuración que se usa en producción real, ya que un proyecto de verdad instalaría el paquete de Tailwind o lo integraría con un empaquetador como Vite, en lugar de depender del CDN. Aun así, la mejor opción sigue dependiendo de cada proyecto y de los gustos personales de quienes lo desarrollan.

Diferencias entre el CDN y la CLI

• Instalación
  • CDN: ninguna, solo una etiqueta <script>.
  • CLI: requiere Node.js y npm.
• Archivo CSS propio
  • CDN: no existe.
  • CLI: se genera un output.css.
• Tailwind IntelliSense
  • CDN: no funciona.
  • CLI: funciona.
• Rendimiento
  • CDN: el navegador genera los estilos en cada carga.
  • CLI: el CSS llega ya compilado y minificado.
• Uso recomendado
  • CDN: pruebas rápidas y aprendizaje.
  • CLI: proyectos reales y despliegues.
• Despliegue
  • CDN: subir el HTML basta.
  • CLI: hay que compilar el CSS en el servidor.

Ese último punto es el que más cambia al publicar tu sitio, y lo explico más abajo.

Requisitos previos

• Node.js y npm instalados. Puedes comprobarlo con node -v y npm -v.
• Un editor como VS Code con la extensión Tailwind CSS IntelliSense instalada.
• Una carpeta de proyecto con un archivo index.html.

Si necesitas reforzar alguno de estos temas, al final del tutorial dejo los cursos recomendados.

Paso 1: inicializar npm e instalar Tailwind

Abre la terminal integrada de VS Code en la carpeta de tu proyecto y ejecuta:

npm init -y
npm install tailwindcss @tailwindcss/cli

El primer comando crea el archivo package.json. El segundo instala Tailwind y su herramienta de línea de comandos.

Paso 2: crear el archivo de entrada

Crea la carpeta src y dentro de ella un archivo llamado input.css con este contenido:

@import "tailwindcss";

Este es el archivo que la extensión IntelliSense detecta para activarse.

Paso 3: compilar el CSS

Ejecuta la CLI indicando el archivo de entrada y el de salida:

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

• -i es el archivo de entrada.
• -o es el archivo de salida, el CSS compilado.
• --watch deja la terminal escuchando y recompila cada vez que guardas un cambio.

Mientras este comando esté corriendo, verás aparecer y actualizarse el archivo src/output.css.

Paso 4: enlazar el CSS en tu HTML

En el <head> de tu index.html agrega:

<link href="./src/output.css" rel="stylesheet">

Presta atención a la ruta. Si tu index.html está en la raíz del proyecto y el CSS compilado está en src/, la ruta correcta es ./src/output.css. En la documentación oficial el HTML también vive dentro de src/, por eso allí aparece ./output.css.

Esta parte la puedes ver de forma directa en la documentación de TailwindCSS. https://tailwindcss.com/docs/installation/tailwind-cli

Con esto ya puedes usar las clases de Tailwind:

<h1 class="text-3xl font-bold underline">Hola mundo</h1>

Paso 5: crear los scripts DEV y BUILD

Escribir el comando completo cada vez es incómodo. Abre tu package.json y agrega estos scripts:

"scripts": {
  "dev": "npx @tailwindcss/cli -i ./src/input.css -o ./src/output.css --watch",
  "build": "npx @tailwindcss/cli -i ./src/input.css -o ./src/output.css --minify"
}

• dev es para trabajar en local. Usa --watch y recompila en tiempo real.
• build es para producción. No usa --watch, porque debe ejecutarse una sola vez y terminar. Además usa --minify para reducir el tamaño del CSS.

Ahora basta con ejecutar:

npm run dev

Y para generar la versión final:

npm run build

Paso 6: configurar el .gitignore

El archivo output.css se genera automáticamente y la carpeta node_modules pesa mucho, así que no deben subirse al repositorio. Crea un archivo .gitignore en la raíz con:

node_modules/
src/output.css

Lo que sí debes subir a Git es el package.json y el package-lock.json, porque con ellos cualquier servidor puede reinstalar las dependencias.

Qué pasa al subirlo a una plataforma de despliegue

Como output.css está en el .gitignore, no existe en tu repositorio. Si solo subes el HTML, tu sitio se verá sin estilos. La solución es que la plataforma ejecute el comando build en cada despliegue. No se puede usar --watch en estos servicios, porque es un proceso que nunca termina y el despliegue se quedaría colgado.

El flujo en cada despliegue es siempre el mismo:

1. La plataforma clona tu repositorio.
2. Ejecuta npm install y descarga Tailwind.
3. Ejecuta npm run build, que genera src/output.css.
4. Publica el sitio, y tu index.html ya encuentra el CSS.

Netlify

Puedes configurarlo en el panel (Site configuration, Build & deploy) o con un archivo netlify.toml en la raíz:

[build]
  command = "npm run build"
  publish = "."

• Build command: npm run build
• Publish directory: . (la raíz, donde está tu index.html)

Vercel

Al importar el proyecto, en la configuración de build elige:

• Framework Preset: Other
• Build Command: npm run build
• Output Directory: .

Heroku

Heroku está pensado para aplicaciones con servidor, así que para un sitio estático necesita un paso adicional. Su buildpack de Node.js ejecuta automáticamente el script build si existe, pero además hace falta algo que sirva los archivos. Una opción es agregar el buildpack estático de la comunidad:

heroku buildpacks:add heroku-community/static
heroku buildpacks:add heroku/nodejs

Y crear un archivo static.json en la raíz:

{
  "root": "."
}

Para un sitio estático como este, Netlify o Vercel suelen ser más sencillos que Heroku.

Consejos generales

• Antes de subir, prueba npm run build en tu computadora. Si genera src/output.css, la plataforma también podrá hacerlo.
• Si el despliegue falla por la versión de Node, puedes fijarla con un archivo .nvmrc o con la variable de entorno NODE_VERSION.
• Si publicas la raíz del proyecto, también quedan accesibles archivos como package.json. No es grave en este caso, pero si prefieres un sitio más limpio, mueve el index.html a una carpeta public y genera ahí el CSS.

Solución a problemas comunes

• La extensión no autocompleta: verifica que exista src/input.css con el @import "tailwindcss" dentro de la carpeta abierta en VS Code. Después recarga la ventana con Ctrl+Shift+P y ejecuta Developer: Reload Window.
• El sitio se ve sin estilos en local: comprueba que npm run dev esté corriendo y que la ruta del href sea correcta.
• El sitio se ve sin estilos en producción: revisa que el build command esté configurado como npm run build en la plataforma.
• Algo de las lecciones no coincide: el curso puede usar una versión distinta de Tailwind. Desde la versión 4 ya no existe tailwind.config.js por defecto ni las directivas @tailwind base, @tailwind components y @tailwind utilities; todo se configura desde el CSS.

Mi configuración

Si quieres ver cómo quedó mi proyecto con la versión 4.3.5 de Tailwind, puedes revisar mi repositorio en GitHub: joedudev/curso-tailwind-platzi.

Dudas y recursos

Si tienes dudas, puedes dejarlas en los comentarios de este tutorial. También puedes reforzar las bases con estos cursos:

• Curso de Introducción a la Terminal y Línea de Comandos
• Curso de NPM: Gestión de Paquetes y Dependencias en JavaScript
• Curso de Git y GitHub