Un sitio de documentación carga hoy 1,6 MB de JavaScript solo para convertir texto en diagramas Mermaid en SVG. Pele logra lo mismo con 230 kB comprimidos y sin ninguna dependencia declarada.
La librería acepta la misma sintaxis que ya usás en Mermaid.js, pero cambia cómo se pintan los colores: en vez de pasar un objeto de tema y volver a ejecutar el renderizador, lee variables CSS directamente del navegador.
TL;DR
- Pele renderiza sintaxis Mermaid a SVG en un bundle de 230 kB gzip, frente a 1,6 MB de Mermaid.js.- render() devuelve el SVG en 0,05 a 0,3 ms, contra 6 a 82 ms de Mermaid.js.- Las variables --pele-bg, --pele-fg y --pele-line recolorean el diagrama sin volver a renderizarlo.- Cero dependencias directas reducen la superficie de auditoría frente a las 23 de Mermaid.js.- npm install pele habilita render() en cualquier proyecto de JavaScript o TypeScript.
¿Qué es Pele?
Pele es una librería de JavaScript de código abierto que renderiza diagramas Mermaid en SVG sin depender de un motor de layout externo ni de un framework de UI. Pesa 230 kB comprimidos, no declara dependencias directas y expone sus colores como variables CSS que cualquier hoja de estilos puede sobrescribir.
El proyecto vive en pele.run, donde el sitio oficial funciona también como editor interactivo: se escribe sintaxis Mermaid a la izquierda y el SVG resultante aparece a la derecha, con un panel aparte para probar las variables de color en vivo.
La propuesta de valor no es agregar funciones nuevas sobre Mermaid.js, sino resolver un problema puntual: renderizar los mismos diagramas con menos peso y menos superficie de dependencias.
El bundle de Mermaid.js pesa 1,6 MB comprimido frente a los 230 kB de Pele.
Por qué importan los diagramas Mermaid en SVG en documentación técnica
Cada diagrama en una página de documentación suma al JavaScript que el navegador tiene que descargar, parsear y ejecutar antes de mostrar nada. Con Mermaid.js, esa factura ronda 1,6 MB comprimidos y 23 dependencias directas, aunque la página solo muestre tres cajas y dos flechas.
Ese costo pesa distinto según el proyecto. Un blog técnico con un diagrama por artículo lo nota poco. Una herramienta interna que renderiza decenas de diagramas por sesión (un visor de arquitectura, un editor de runbooks, un generador de documentación a partir de código) sí lo nota, porque cada render repite el costo de parseo y layout.
Pele ataca justamente ese caso. Su bundle gzip pesa 230 kB y su tiempo de render va de 0,05 a 0,3 ms, frente a 6 a 82 ms de Mermaid.js. La diferencia se nota más cuanto más diagramas hay en una misma página, porque cada diagrama paga su propio tiempo de render.
Cómo funciona Pele por dentro
La función central de la librería es render(): recibe un string con sintaxis Mermaid y devuelve un objeto con una propiedad svg, que es el markup SVG completo listo para insertar en el DOM. No hay paso intermedio de configuración ni un objeto de tema que pasar como segundo argumento.
La parte que distingue a Pele está en cómo ese SVG define sus colores. En vez de escribir atributos con valores fijos calculados en el momento del render, los elementos del SVG referencian variables CSS, por ejemplo fill="var(--pele-fg)". El navegador resuelve esa variable al pintar, no la librería al generar el SVG.
Esa diferencia es la que permite cambiar de tema sin volver a renderizar. Si el color estuviera fijo en el atributo, cambiar de claro a oscuro obligaría a llamar render() de nuevo y reemplazar el SVG completo en el DOM; con variables CSS alcanza con cambiar el valor de --pele-bg en una regla CSS.
flowchart LR
A["Sintaxis Mermaid"] --> B["Parser interno"]
B --> C["Calculo de layout"]
C --> D["SVG con var(--pele-fg)"]
D --> E(["Navegador"])
El mismo mecanismo explica por qué la demo oficial permite cambiar colores sin que el diagrama se vuelva a dibujar: el paso "SVG con var(--pele-fg)" del diagrama de arriba ya ocurrió una sola vez, y de ahí en adelante el navegador se encarga del repintado.
Ejemplos prácticos con código progresivo
El primer ejemplo es el equivalente a un hola mundo: tomar un diagrama de flujo simple y mostrarlo en pantalla.
import { render } from 'pele';
const { svg } = render(`flowchart LR
A[Build] --> B[Test]
B --> C[Deploy]`);
document.querySelector('#diagrama').innerHTML = svg;
console.log(svg.startsWith(' {
contenedor.classList.toggle('oscuro');
});
sequenceDiagram
participant U as Usuario
participant J as JS de la pagina
participant C as CSS
participant S as SVG renderizado
U->>J: clic en boton modo oscuro
J->>C: alterna la clase oscuro
C->>S: el navegador repinta var(--pele-bg)
Note over S: no se llama render de nuevo
Para confirmar que el theming está realmente activo hay que inspeccionar el elemento en las devtools del navegador: si el atributo fill de un nodo muestra var(--pele-fg) en lugar de un valor hexadecimal fijo, la variable está conectada. Si en cambio aparece un color fijo, algo en el build (un minificador de CSS agresivo, por ejemplo) resolvió la variable antes de tiempo.
Mermaid.js declara 23 dependencias directas; Pele no declara ninguna.
Cómo empezar: instalación y primer render
Lo único que necesitás antes de instalar Pele es tener Node.js y un gestor de paquetes en la máquina; el comando es idéntico en Windows, macOS y Linux.
npm install pele
Si tu proyecto usa otro gestor, el paquete se instala igual con pnpm add pele, yarn add pele o bun add pele.
Con el paquete instalado, el primer render completo en una página HTML queda así:
import { render } from 'pele';
const diagrama = `flowchart TD
A[Peticion HTTP] --> B{Cache valido?}
B -- Si --> C[Responder desde cache]
B -- No --> D[Consultar origen]
D --> E[Guardar en cache]
E --> C`;
const { svg } = render(diagrama);
document.querySelector('#diagrama').innerHTML = svg;
No hay paso de inicialización ni un objeto de configuración que crear antes de llamar a render(). Eso es consistente con la cifra de cero dependencias directas: no hay un motor de plugins que configurar primero.
💡 Tip: combinar las variables CSS de Pele con
prefers-color-schemeevita escribir JavaScript para el modo oscuro: una media query que redefina--pele-bgy--pele-fgalcanza para que el diagrama respete la preferencia del sistema operativo sin un listener de clic.
Casos de uso reales
El caso más directo es cualquier sitio estático que ya escribe diagramas en sintaxis Mermaid dentro de Markdown: generadores de documentación, wikis internas, blogs técnicos. En vez de cargar el bundle completo de Mermaid.js en cada página, un paso de build puede recorrer los bloques de código marcados como Mermaid y llamar a render() una sola vez por diagrama, dejando el SVG ya resuelto en el HTML final.
Otro caso es el de herramientas internas que generan diagramas dinámicamente a partir de datos: un visor de dependencias entre microservicios, un editor de runbooks de incidentes, un panel que dibuja el estado de una pipeline de CI en tiempo real. Ahí el tiempo de render por diagrama se nota en la latencia percibida de la interfaz.
Un tercer caso es el de editores o extensiones que muestran una vista previa del diagrama mientras el usuario escribe: ahí el costo de re-renderizar en cada tecla es lo primero que se siente si la librería es pesada.
Errores comunes y buenas prácticas
El error más común es olvidar la clase pele (o el equivalente que definas) en un ancestro del SVG. Las variables CSS de Pele no son globales por defecto: si las declarás en una clase que nunca envuelve al contenedor del diagrama, el SVG usa sus valores por defecto y el cambio de color simplemente no aparece.
El segundo error es confundir qué cambios necesitan volver a llamar render() y cuáles no. Cambiar un color definido como variable CSS no lo necesita, el navegador repinta solo. Pero cambiar el contenido del diagrama sí requiere ejecutar render() de nuevo con el string actualizado: las variables CSS resuelven el theming, no la estructura.
⚠️ Ojo: si el texto que le pasás a
render()viene de un usuario final y no de tu propio código, tratalo como entrada no confiable antes de insertar el resultado coninnerHTML. Un SVG puede incluir elementos como<script>o manejadores de evento embebidos; sanitizar el SVG resultante (por ejemplo con DOMPurify configurado para SVG) es una precaución razonable en cualquier flujo donde el diagrama no lo escribiste vos.
Por último, antes de asumir que Pele corre igual en un script de build de Node que en el navegador, probalo en ese entorno concreto: la demo de pele.run muestra el uso en el navegador, y confirmar que render() no depende de ninguna API específica del DOM es algo que conviene verificar en tu propio proyecto antes de depender de ello en producción.
Comparativa: Pele vs Mermaid.js
La tabla resume las cifras que pele.run publica comparando ambas librerías sobre el mismo tipo de diagrama.
MétricaPeleMermaid.jsBundle (gzip)230 kB1,6 MBTiempo de renderizado0,05 a 0,3 ms6 a 82 msDependencias directas023ThemingVariables CSS, sin re-renderObjeto de configuración de temaPantallas pequeñasAdapta el layoutEscala el diagrama completo
La fila de pantallas pequeñas importa más de lo que parece: adaptar el layout significa reorganizar nodos para que entren en el ancho disponible, mientras que escalar el diagrama completo achica también el texto, que puede quedar ilegible en una pantalla de teléfono.
Profundizando: theming, accesibilidad y límites de Pele
El modelo de variables CSS tiene una ventaja de accesibilidad que no es obvia a primera vista: como el texto del diagrama sigue siendo texto SVG real, no una imagen rasterizada, un lector de pantalla puede leerlo y un usuario puede seleccionarlo y copiarlo. Esto no es exclusivo de Pele, Mermaid.js también emite SVG con texto real, pero es una propiedad que se pierde si en algún punto del pipeline el SVG se convierte a PNG para incrustarlo en un PDF.
La elección entre adaptar el layout o escalar el diagrama completo en pantallas chicas es una decisión de diseño con compromisos en ambas direcciones: reorganizar nodos mantiene el texto legible pero puede alargar mucho el diagrama en vertical, mientras que escalar todo preserva las proporciones originales pero sacrifica legibilidad. Una jerarquía angosta se adapta mejor a reorganizarse; un diagrama ancho con muchos nodos en el mismo nivel sufre más con cualquiera de las dos estrategias.
flowchart TD
A["Necesitas diagramas Mermaid"] --> B{"Bundle size y dependencias importan?"}
B -- "Si" --> C["Pele"]
B -- "No, ya usas Mermaid.js" --> D["Mermaid.js"]
C --> E(["SVG final"])
D --> E
Esa decisión también depende de cuánta cobertura de sintaxis necesitás. Mermaid.js acumuló años de tipos de diagrama (Gantt, estados, clases, entidad-relación, mapas mentales, entre otros) y una comunidad grande alrededor de esa sintaxis extendida. Antes de migrar un proyecto completo de Mermaid.js a Pele conviene revisar, diagrama por diagrama, si el tipo que usás está soportado en la documentación de pele.run, no asumirlo porque ambas acepten sintaxis Mermaid.
📖 Resumen en Telegram: Ver resumen
Tu próximo paso: abrí el editor interactivo de pele.run, cambiá el valor de --pele-bg desde las devtools del navegador y confirmá en la pestaña Elements que el <svg> sigue mostrando var(--pele-bg) en vez de un color fijo.
Preguntas frecuentes
¿Pele reemplaza completamente a Mermaid.js?
No necesariamente. Pele cubre el caso de renderizar sintaxis Mermaid a SVG con menos peso y un theming más simple, pero Mermaid.js tiene más tipos de diagrama acumulados a lo largo de los años. Conviene revisar si los tipos que usás están soportados antes de migrar un proyecto entero.
¿Los diagramas Mermaid en SVG generados por Pele funcionan sin conexión a internet?
Sí, una vez instalado el paquete, render() corre localmente: no hace ninguna petición de red para convertir la sintaxis en SVG. El resultado tampoco depende de recursos externos para mostrarse, salvo que vos mismo agregues imágenes o fuentes externas dentro del diagrama.
¿Pele soporta todos los tipos de diagrama de Mermaid.js?
El sitio oficial muestra flowcharts en su demo principal; para confirmar la cobertura de otros tipos (secuencia, clases, Gantt, estados) hay que revisar la documentación del proyecto en pele.run en lugar de asumir paridad total con Mermaid.js.
¿Puedo usar Pele con React, Vue o Svelte?
Sí, porque render() devuelve un string de SVG, no un componente atado a un framework. En React se puede insertar con dangerouslySetInnerHTML, en Vue con v-html y en Svelte con {@html}, siempre con las mismas precauciones de sanitización si el contenido viene de un usuario.
¿Qué pasa si el SVG generado por Pele no se ve bien en pantallas chicas?
Pele adapta el layout en pantallas pequeñas en lugar de escalar el diagrama completo, lo que mantiene el texto legible a costa de reorganizar los nodos. Si un diagrama específico sigue viéndose mal, revisar si tiene muchos nodos en el mismo nivel ayuda a diagnosticar el problema.
¿Pele funciona en Node.js sin navegador?
No hay confirmación directa de esto en la documentación pública del proyecto. Antes de depender de un uso en build time o en el servidor conviene probarlo en ese entorno concreto, en vez de asumir que la ausencia de dependencias implica ausencia de APIs del navegador.
Referencias
- Pele: sitio oficial del proyecto, con editor interactivo, API de instalación y la comparativa de rendimiento contra Mermaid.js.- Mermaid.js: documentación oficial de la librería que define la sintaxis que ambos proyectos comparten.- MDN: uso de propiedades personalizadas de CSS: referencia sobre cómo funcionan las variables CSS que usa Pele para el theming.
📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.
