Ahórrate unas horas!!! Aquí tienes una guía práctica para usar tailwind css v4 en Docusaurus sin romper sus estilos y con consejos reales para producción.
Problema común: tailwind incluye preflight que reinicia estilos globales y puede chocar con los estilos del tema de Docusaurus. Además las utilidades globales pueden sobreescribir selectores propios y componentes del framework. La buena noticia es que hay varias soluciones limpias y escalables.
Paso 1 Instalación básica y archivos clave Instala tailwind css v4 junto a postcss y autoprefixer con npm install -D tailwindcss@4 postcss autoprefixer y genera la configuración con npx tailwindcss init -p. Esto crea tailwind.config.cjs y postcss.config.cjs. Crea el archivo de estilos globales src/css/custom.css y añade las directivas @tailwind base; @tailwind components; @tailwind utilities;
Paso 2 Rutas de contenido Configura tailwind.config.cjs para que analice los archivos de tu sitio incluyendo componentes y archivos mdx por ejemplo content [./src/**/*.{js,jsx,ts,tsx,mdx}, ./docs/**/*.{md,mdx}] y si necesitas incluir código del theme añade ./node_modules/@docusaurus/theme-classic/src/**/*.{js,jsx,ts,tsx} para evitar que clases se eliminen en purge o content stripping.
Paso 3 Evitar que preflight rompa estilos Opción A desactivar preflight en tailwind.config.cjs con corePlugins { preflight false } Opción B usar prefix para todas las utilidades prefix tw- de esta forma las clases tailwind no colisionan con clases existentes Opción C scoping con important que puede ser un selector por ejemplo important #__docusaurus para que las utilidades sólo afecten al árbol dentro del id raíz de Docusaurus Cada opción tiene trade offs desactivar preflight evita resets pero pierdes normalización; prefix evita colisiones pero exige usar prefijos en todo; important scopa estilos sin renombrar clases y suele ser la opción más práctica para integrar sin romper el theme.
Paso 4 Integración en Docusaurus Añade src/css/custom.css al preset classic de Docusaurus en la propiedad customCss para que se cargue con el sitio. Si prefieres cargado inicial usa clientModules con la ruta a tu archivo css. Asegúrate de que el orden de carga es correcto si usas otros estilos globales: si quieres que tailwind no reescriba estilos del theme carga tailwind antes y usa preflight false o prefix; si quieres que tailwind prevalezca carga tailwind después o usa important selector.
Paso 5 Mejor práctica componentes usa css modules o estilos en módulos para componentes React y evita depender exclusivamente de utilidades globales para estilos muy específicos. De este modo mantienes compatibilidad con actualizaciones del tema y reduces riesgos al actualizar Docusaurus o tailwind.
PostCSS y orden de plugins revisa postcss.config.cjs y verifica que tailwindcss y autoprefixer estén presentes y en el orden correcto. Para builds de producción comprueba que el proceso de purge o content trimming incluya todas las rutas relevantes para evitar que classes útiles sean eliminadas.
Comprobaciones finales ejecuta npm run start y npm run build revisa el sitio en distintos navegadores y tamaños de pantalla y usa herramientas de inspección para localizar overrides inesperados. Si detectas conflictos prueba a activar important selector temporalmente para identificar la fuente del override.
Si quieres una solución lista para producción considera estas recomendaciones combinadas usa prefix para utilidades globales en proyectos grandes, usa important con un selector raíz para integrar rápidamente en Docusaurus y emplea css modules para componentes críticos. Con estas medidas puedes mantener la potencia de tailwind css v4 sin sacrificar la coherencia del tema de Docusaurus.
En Q2BSTUDIO somos especialistas en integrar tecnologías modernas y optimizar tiempos de desarrollo. Ofrecemos desarrollo de software a medida y aplicaciones a medida, consultoría en inteligencia artificial e ia para empresas, arquitecturas seguras y ciberseguridad, así como servicios cloud aws y azure. También entregamos servicios inteligencia de negocio, soluciones con power bi, agentes ia y proyectos completos de inteligencia artificial para empresas. Si necesitas que integremos tailwind css v4 en tu sitio Docusaurus, o que desarrollemos software a medida o aplicaciones a medida con garantías de seguridad y escalabilidad en cloud aws y azure, en Q2BSTUDIO podemos ayudarte a ahorrar tiempo y evitar errores comunes.
Palabras clave para encontrar nuestros servicios aplicaciones a medida software a medida inteligencia artificial ciberseguridad servicios cloud aws y azure servicios inteligencia de negocio ia para empresas agentes ia power bi.
