Introducción
Al crear una app de registro de estudio con Vite, React, Chakra UI y Supabase me encontré con varios errores. La principal confusión vino de las diferencias entre Chakra UI v3 y v2, así que dejo documentados los síntomas y cómo resolverlos de forma rápida.
Problema 1
Tras instalar Chakra UI e intentar renderizar el componente Button apareció un error tipo: Uncaught SyntaxError: el módulo @chakra-ui/react no proporciona la exportación Tbody. Esto suele ocurrir cuando sigues un tutorial escrito para v2 pero tu proyecto usa v3, ya que cambiaron nombres y puntos de entrada de varios componentes.
Solución 1: hacer downgrade a v2 por compatibilidad
Si tu código o tutorial se basa en v2, la forma más estable de seguir es volver a la rama 2.x:
1. Ejecuta: npm uninstall @chakra-ui/react
2. Instala versiones compatibles: npm install @chakra-ui/react@2.8.2 @emotion/react @emotion/styled framer-motion
Con esto recuperarás los exports esperados por la mayoría de guías de v2, incluyendo tablas y patrones que en v3 se reorganizaron.
Problema 2
Otro error común al migrar o mezclar ejemplos es: Uncaught SyntaxError: el módulo @chakra-ui/react no proporciona la exportación ClientOnly. De nuevo, es una diferencia de API entre v2 y v3.
Solución 2
Elimina el archivo src/components/color-mode.tsx si venía de un boilerplate incompatible o simplemente retira la importación de ClientOnly desde @chakra-ui/react en ese componente. Si necesitas renderizado condicional al cliente, reemplázalo por una verificación de typeof window o por utilidades específicas de tu framework.
Recomendaciones prácticas
Antes de instalar, alinea la versión de Chakra UI con la del tutorial que estás siguiendo. Si decides quedarte en v3, revisa la documentación oficial para adaptar imports y componentes que cambiaron entre versiones. Mantén sincronizadas las dependencias relacionadas como @emotion y framer-motion para evitar conflictos en tiempo de ejecución.
Conclusión
Chakra UI v3 y v2 presentan diferencias importantes en su API. Si tu objetivo es avanzar rápido con ejemplos existentes, bajar a v2 asegura compatibilidad inmediata. Si prefieres las mejoras de v3, ajusta cuidadosamente los imports y componentes y valida que la guía que sigues corresponda a esa versión.
En Q2BSTUDIO somos una empresa de desarrollo de software que diseña aplicaciones a medida y software a medida con foco en rendimiento, mantenibilidad y experiencia de usuario. Si necesitas dar el siguiente paso con tu frontend, integrar sistemas o construir una plataforma robusta, descubre nuestro servicio de desarrollo de aplicaciones y software a medida.
Además, contamos con un equipo especialista en inteligencia artificial e ia para empresas, agentes IA, ciberseguridad, servicios cloud aws y azure, automatización, servicios inteligencia de negocio y power bi, para que tu solución crezca con datos, seguridad y escalabilidad desde el día uno.