Programación

Vite, Tailwind v4 y Google Auth: Guía de supervivencia ante errores de despliegue

d450330 22.4kb

PUNTOS CLAVE

  • Migra de @tailwind a @import "tailwindcss"; para evitar archivos CSS vacíos en producción.
  • Configura la CSP en el servidor (.htaccess) porque las cabeceras HTTP anulan las etiquetas meta del HTML.
  • Desactiva la caché del index.html para prevenir errores 404 al regenerar bundles con nuevos hashes.
  • Asegura los dominios de Google y Firebase en la política de seguridad para no romper el inicio de sesión.

Desplegar una aplicación moderna hoy en día puede convertirse en un laberinto de configuraciones invisibles. Lo que funciona perfectamente en tu entorno local con Vite a menudo se rompe al subirlo al servidor por culpa de una política de seguridad agresiva o una caché mal gestionada. Si estás intentando solucionar errores de despliegue en Vite y Tailwind v4, sabrás que la transición entre versiones oculta trampas que pueden dejar tu web sin estilos o con un sistema de autenticación totalmente bloqueado.

#El misterio de los 20KB: Tailwind v4 y Vite

Uno de los fallos más frustrantes al actualizar a Tailwind CSS v4 es descubrir que, tras el build, tu archivo CSS de producción apenas ocupa 20KB. El síntoma es claro: la web se ve «rota», solo con los estilos base pero sin ninguna de tus clases personalizadas. Esto sucede porque las versiones más recientes de Vite y sus plugins han cambiado la forma en que escanean el código.

La solución oficial (y necesaria) es abandonar las antiguas directivas de Tailwind y tratarlas como imports de CSS estándar. Sin este cambio, el motor de procesado a veces ignora los archivos HTML y no inyecta los «átomos» de estilo necesarios.

TIP PRO

Después de cada npm run build, verifica siempre el peso del archivo CSS en la carpeta dist/assets/. En un proyecto de tamaño medio, debería superar los 60KB. Si ves algo cercano a los 20KB, la compilación de estilos ha fallado silenciosamente.

Modificar en el archivo principal styles.css:

css
/* ❌ Sintaxis antigua que puede fallar en Vite v6+ */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* ✅ Nueva sintaxis mandatoria para Tailwind v4 */
@import "tailwindcss";

#Google Auth y el bloqueo de CSP en el servidor

Si usas Firebase Auth o Google Sign-In, es probable que te hayas topado con errores de tipo unsafe-inline o bloqueos de scripts de apis.google.com. Lo que muchos desarrolladores olvidan es que las cabeceras del servidor (.htaccess en Apache) tienen prioridad absoluta sobre cualquier etiqueta <meta> que pongas en tu HTML.

Si tu hosting aplica una política de seguridad (CSP) restrictiva por defecto, tu web ignorará tus intentos de arreglarlo desde el código. La solución pasa por tomar el control del archivo .htaccess y definir allí explícitamente qué dominios tienen permiso para ejecutar scripts y cargar marcos.

NOTA TÉCNICA

La cabecera Content-Security-Policy es acumulativa. Si el servidor envía una y tú pones otra en el HTML, el navegador aplicará la más restrictiva de las dos. Por eso el .htaccess es tu única herramienta real aquí.

#Troubleshooting: Errores comunes en producción

PROBLEMA COMÚN

Errores 404 repentinos en archivos JS y CSS tras una actualización. Esto ocurre porque el navegador del usuario tiene guardado el index.html viejo, que busca nombres de archivo con hashes que ya no existen en el servidor.

Para evitar este «infierno» de la caché, debemos configurar el servidor para que el archivo HTML se valide siempre, mientras que los assets (que tienen nombres únicos) pueden vivir más tiempo en memoria.

Configurar en la raíz del sitio dentro de .htaccess:

apache
# ✅ Forzamos que el navegador compruebe siempre si hay un nuevo HTML
<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType text/html "access plus 0 seconds"
</IfModule>

# ✅ Configuración de CSP completa para Google Auth y Tailwind
<IfModule mod_headers.c>
    Header always set Content-Security-Policy "default-src 'self' https://*.google.com https://*.gstatic.com https://*.googleapis.com https://*.firebaseio.com https://*.firebaseapp.com; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://apis.google.com https://www.google.com https://www.gstatic.com https://*.googleapis.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://cdn.jsdelivr.net; img-src 'self' data: https: https://*.googleusercontent.com;"
</IfModule>

#¿Cuándo aplicar estas medidas?

Estas configuraciones no son opcionales para proyectos que escalan más allá de un simple prototipo. Debes aplicarlas si te encuentras en alguno de estos escenarios:

  • Aplicaciones que usan autenticación de terceros (Google, Microsoft, etc.).
  • Webs que requieren una carga de estilos crítica y no pueden permitirse parpadeos (FOUC) o fallos de renderizado.
  • Entornos de hosting compartido o managed donde no tienes acceso a la configuración global de Nginx o Apache.
  • Proyectos con actualizaciones frecuentes donde la invalidación de caché es vital.

#Caso real: El misterio del CSS de 22KB

Hace poco me encontré con un despliegue donde, tras una actualización de dependencias, la web se veía como en 2005. Al revisar las herramientas de desarrollador, el archivo CSS cargaba correctamente (HTTP 200), pero su contenido era una sombra de lo que debía ser. Solo el reset de estilos estaba ahí.

Mi primer intento fue añadir !important a todo y forzar la inclusión de archivos CSS en el tailwind.config.js. Un error clásico de novato. Tras media hora de frustración, el culpable apareció en la documentación de la v4: el cambio de sintaxis en el import. Es ese tipo de detalles —pequeños pero demoledores— los que te arruinan la tarde si no estás atento al log de la terminal durante el build.

#Pros y Contras de este enfoque

Ventaja Inconveniente
Seguridad total contra inyecciones XSS mediante CSP estricta. Requiere mantenimiento manual si decides usar nuevas librerías externas.
Garantía de que el usuario siempre ve la última versión (Adiós caché). Ligero aumento de las peticiones iniciales al no cachear el HTML.
Compilación de estilos optimizada para las últimas versiones de Vite. Curva de aprendizaje al abandonar las directivas @tailwind tradicionales.

Esto lo escribo en marzo de 2026 con Vite 7.3 y Tailwind 4.2. Si has llegado aquí mucho tiempo después, echa un vistazo a la documentación de los bundlers, porque la guerra entre imports nativos y directivas de post-procesado sigue evolucionando rápidamente.

PROTOCOLO DE RESCATE

Si tras aplicar el .htaccess tu web da un error 500, bórralo inmediatamente. Es probable que tu servidor no tenga activado mod_headers o mod_expires. Consulta con tu soporte técnico antes de intentar forzar cabeceras de seguridad.

Más información en la documentación de Tailwind CSS v4 y las guías de despliegue de Vite.