Hace dos semanas estaba construyendo documentación para un proyecto de un cliente y necesitaba diagramas de flujo. Simple, verdad? Error.
Pasé 3 horas peleando con soluciones Mermaid existentes. Configuraciones que fallaban, temas que no conmutaban correctamente, SSR protestando. Hubo un momento en el que consideré dibujar los diagramas en Figma e incrustar imágenes como un bárbaro.
Ahí me cayó la ficha: seguimos tratando Mermaid como si fuera 2019. Importar librerías, pelear con la inicialización, rezar para que funcione con tu sistema de build. Pero esto es Svelte 5. Tenemos runes. Por qué seguimos programando como plebeyos?
Así nació @friendofsvelte/mermaid, la forma en que los diagramas deberían funcionar en 2025.
Uso en una frase: importas el componente Mermaid desde el paquete y le pasas una cadena con tu diagrama. El componente inicializa, renderiza y vuelve a renderizar cuando cambian los datos, sin malabares con SSR ni temas.
Lo que aprendí construyéndolo
Integrar Mermaid está sobrepensado. Muchas soluciones intentan cubrir todos los casos y versiones posibles. Resultado: APIs infladas que no se sienten propias de Svelte.
Las runes lo cambiaron todo. Donde antes había decenas de sentencias reactivas, ahora basta con $state y $derived para gestionar estado de forma clara y limpia.
La tematización era el verdadero dolor. En lugar de pelear con variables CSS y overrides frágiles, el componente acepta un prop de tema y se encarga de todo, con cambios instantáneos.
Qué hace realmente
Temas que cambian al instante, con modo oscuro, colores personalizados y sin parpadeos.
TypeScript de verdad, con tipado completo y autocompletado útil.
Compatibilidad con todos los tipos de diagrama: flujo, secuencia, Gantt, user journeys y más.
Manejo de errores que ayuda, con mensajes claros cuando hay problemas de sintaxis.
Diseño responsive por defecto, funciona perfecto en móviles sin tocar nada.
La parte controvertida
La mayoría de integraciones de Mermaid están resolviendo el problema equivocado. Se centran en compatibilidad y en la lista de funciones en lugar de la experiencia del desarrollador. Si tu componente de diagramas se siente como trabajo extra, documentarás menos.
Las herramientas de documentación deben desaparecer. Tienes que pensar en tu contenido, no en tu tooling.
Por qué esto importa
He visto demasiados proyectos con documentación pobre porque las herramientas de diagramas eran un suplicio. Los equipos evitan los diagramas de flujo, ignoran los de secuencia y terminan con documentación que nadie entiende.
Cuando añadir diagramas es tan simple como escribir markdown, los equipos documentan de verdad. Y eso hace mejor al software.
Pruébalo
Sitio de la demo: ver Mermaid funcionando. Instalación con npm: npm install @friendofsvelte/mermaid. Compatible solo con Svelte 5.
Lo que viene
Esto forma parte de un toolkit de documentación más grande en el que estoy trabajando: componentes para documentación de APIs, ejemplos de código interactivos y quizá demos en vivo embebidas.
En Q2BSTUDIO ayudamos a equipos a construir y mantener documentación excelente como parte de sus productos. Somos una empresa de desarrollo de software que crea aplicaciones a medida y software a medida, y podemos integrar este tipo de componentes en tus procesos de entrega, CI CD y SSG SSR con Svelte 5. Si buscas un partner para acelerar tu roadmap, visita nuestro servicio de desarrollo de software y aplicaciones a medida.
Además, ofrecemos soluciones de inteligencia artificial e ia para empresas, diseño de agentes IA, ciberseguridad con enfoque en pentesting, servicios cloud aws y azure, servicios inteligencia de negocio y power bi, y automatización de procesos de extremo a extremo. Si necesitas un equipo que entienda tanto el producto como la plataforma, podemos ayudarte a convertir documentación y tooling en una ventaja competitiva. Conoce también nuestras aplicaciones a medida multiplataforma.
Qué tipo de diagramas estás añadiendo a tus proyectos? También te frustra lo complejo que se ha vuelto algo que debería ser simple?