Integrando Astro 5, Storybook 9, Vite 7 y Tailwind 3

Integrando Astro 5, Storybook 9, Vite 7 y Tailwind 3 puede convertirse en un rompecabezas si se mezclan dependencias implícitas y configuraciones esperadas por herramientas distintas. En esencia, Storybook no entiende archivos .astro nativos, pero sí entiende componentes escritos en JSX o TSX, y Astro puede renderizar componentes React, Solid o Svelte a HTML estático cuando omitimos directivas client. Esto permite escribir componentes en React incluso cuando su contenido es estático y usarlos en Storybook como ejemplos funcionales.

El flujo práctico es escribir las piezas visibles como componentes React y exponer ejemplos o datos desde las colecciones de contenido de Astro a esos componentes. Esa estrategia fue señalada por desarrolladores como Matt Fantinel y Antonio Pitasi y funciona bien para obtener vistas interactivas y reproducibles en Storybook.

El problema más habitual aparece al integrar Tailwind con Storybook y Vite. La documentación oficial sugiere que basta con importar nuestro archivo global de Tailwind desde .storybook/preview.ts e instalar PostCSS cuando sea necesario. Sin embargo, con Astro 5, tailwind 3.3, Storybook 9 y Vite, la integración mediante PostCSS puede fallar silenciosamente: el servidor de Storybook muestra un spinner infinito o un error 500 interno sin registros claros, mientras que el servidor de Astro para desarrollo y la build de producción funcionan correctamente con la misma configuración de Tailwind.

Una recomendación común es añadir explícitamente un archivo de configuración PostCSS. Por ejemplo, crear un archivo postcss.config.js que exponga plugins con tailwindcss y autoprefixer. En algunos entornos esto soluciona la compilación, pero en otros provoca el error mencionado en Storybook. La raíz suele ser una discrepancia entre versiones de PostCSS usadas por Astro, Vite y Storybook o un conflicto en cómo Vite y Storybook cargan la configuración PostCSS en proyectos monorepo o con paquetes enlazados.

Pasos prácticos que conviene probar para resolver la integración

1 Alinear la versión de PostCSS Instalar explícitamente postcss en la versión 8 si alguna dependencia lo espera y asegurarse de que tailwindcss y autoprefixer están presentes como dependencias de desarrollo.

2 Archivo de PostCSS dedicado para Storybook Crear postcss.config.cjs en la raíz y verificar que Storybook lo detecta. En algunos casos es útil añadir una configuración específica dentro de .storybook/main para forzar la carga o usar viteFinal para mezclar la configuración de Vite con la de Storybook.

3 Importar CSS global en preview Confirmar que .storybook/preview.ts importa el archivo css global que contiene las directivas Tailwind como tailwind base components utilities. Evitar rutas relativas que puedan resolverse distinto según el proceso que ejecuta Storybook.

4 Usar el builder Vite en Storybook Asegurarse de que en .storybook/main el core y el framework apuntan a la configuración de Vite, por ejemplo usando @storybook/builder-vite y @storybook/react-vite para que la resolución de plugins PostCSS y los plugins de Vite sea consistente.

5 Depuración más profunda Ejecutar Storybook con niveles de log más altos y revisar tanto stderr como los ficheros temporales y la caché de node modules. Borrar la caché de Storybook y node_modules puede ayudar. Si persiste un error 500 sin logs, probar a simplificar historias hasta identificar la regla CSS o plugin que provoca el fallo.

Si tras estas comprobaciones el problema continúa, alternativas prácticas incluyen escribir las historias en React puro y alimentar los componentes con contenido preprocesado desde Astro durante el paso de build, o montar un proceso separado para generar el CSS de Tailwind y servirlo estáticamente a Storybook para aislar la capa de PostCSS del runtime de Storybook.

En Q2BSTUDIO, empresa especializada en desarrollo de software y aplicaciones a medida, inteligencia artificial, ciberseguridad y servicios cloud aws y azure, ayudamos a equipos a resolver integraciones complejas como esta. Ofrecemos servicios de software a medida, aplicaciones a medida, consultoría en inteligencia artificial e ia para empresas, agentes IA y soluciones de inteligencia de negocio y power bi para mejorar la gobernanza de datos y el análisis. También implementamos buenas prácticas de seguridad y despliegue continuo para evitar discrepancias entre entornos de desarrollo y producción.

Si necesitas apoyo para alinear versiones de PostCSS, configurar Storybook con Vite y Tailwind, o migrar componentes Astro a un flujo compatible con Storybook, Q2BSTUDIO puede auditarr tu proyecto, proponer una configuración reproducible y aplicar soluciones concretas que faciliten desarrollo y testing. Contáctanos para una auditoría técnica y una propuesta adaptada a tus necesidades en integración frontend y modernización de pipelines.

En resumen, la integración es posible pero requiere atención a versiones y a cómo Storybook carga PostCSS. Alinear dependencias, usar un builder Vite coherente y, cuando haga falta, separar la generación de CSS, suele resolver la mayoría de los casos. Si quieres, podemos revisar tu repo y ofrecer una solución personalizada.