Beautiful Mermaid: renderizado de diagramas Mermaid sin dependencias de DOM

El Pitch

Beautiful Mermaid es una librería en TypeScript diseñada para convertir código de Mermaid en SVG de alta calidad o arte ASCII/Unicode directamente en el servidor. Su propuesta central elimina la necesidad de un navegador o entornos con DOM, permitiendo su ejecución nativa en entornos modernos de ejecución. (fuente: GitHub)

La comunidad en Hacker News ha puesto el foco en esta herramienta por su capacidad de integrar diagramas en terminales y documentación estática sin el overhead de Puppeteer o Playwright. Es una solución ligera para quienes buscan velocidad de renderizado en procesos de CI/CD o aplicaciones CLI. (fuente: HN)

Bajo el capó

Técnicamente, el motor de renderizado ASCII es un port directo del proyecto 'mermaid-ascii' escrito originalmente en Go por Alexander Grooff. La versión de Lukilabs extiende esta funcionalidad añadiendo soporte para SVG y una integración nativa con Shiki para el manejo de temas visuales. (fuente: GitHub / HN)

Actualmente, la librería permite trabajar en Node.js, Bun y Deno, manteniendo una arquitectura de cero dependencias de DOM. En cuanto a rendimiento, los desarrolladores reportan el procesamiento de más de 100 diagramas en menos de 500ms. (fuente: Lukilabs/GitHub)

Sin embargo, el soporte de esquemas es limitado comparado con la implementación oficial de Mermaid.js que manejamos en este 2026. Los puntos clave de su estado actual son:
- Soporta únicamente 5 tipos de diagramas: Flowcharts, State, Sequence, Class y ER. (fuente: GitHub)
- Incluye 15 temas predefinidos y compatibilidad total con Shiki. (fuente: GitHub)
- Presenta errores documentados al renderizar nodos de inicio ([*]) en stateDiagram-v2. (fuente: HN)
- Carece de soporte para los más de 20 tipos de diagramas de la librería oficial. (fuente: GitHub)
- No soporta elementos interactivos, tooltips o hipervínculos por su naturaleza estática. (fuente: Dossier UsedBy)

A día de hoy, todavía no existen benchmarks oficiales que comparen su desempeño contra el renderizado nativo de Mermaid.js bajo las arquitecturas de CPU actuales. Tampoco se ha publicado una hoja de ruta clara para integrar las funciones avanzadas de interacción que ya son estándar en otros visualizadores. (fuente: Dossier UsedBy)

La opinión de Diego

Beautiful Mermaid no es un sustituto para Mermaid.js en aplicaciones web complejas, pero es una herramienta obligatoria para herramientas de CLI y generadores de sitios estáticos que priorizan la velocidad. Si usas Kroki, ya tienes cubiertas la mayoría de estas funciones, pero si necesitas una ejecución local pura en TypeScript sin levantar servicios externos, esta es la opción ganadora. Úsala en producción solo si tus diagramas se limitan a los cinco tipos soportados y no dependes de la sintaxis de stateDiagram-v2, que sigue rota. Para todo lo demás, sigue siendo un juguete técnico interesante para side-projects.

Código limpio siempre,
Diego.