GeekChart es una librería open source que transforma diagramas escritos en sintaxis Mermaid en gráficos SVG animados con la estética visual de 4Geeks. El paquete ofrece tres puntos de entrada: un componente React para edición en navegador, una función server-side para generación estática, y una CLI para exportar a archivos independientes. Según el README del repositorio oficial, el parser diferido carga solo cuando el visitante interactúa con el primer diagrama, lo que mantiene el bundle inicial ligero.
Por qué GeekChart existe cuando ya hay Mermaid
Mermaid.js parsea y renderiza diagramas, pero no anima ni garantiza consistencia visual. Wafic Mikati, desarrollador del equipo 4Geeks, construyó GeekChart para cubrir esos vacíos: animación con vocabulario de Manim (trazos que aparecen, rellenos que siguen, un solo movimiento por vez), sistema de diseño propio con tokens en packages/core/src/tokens.ts, y un gate de medición que falla el build si cualquier diagrama incumple las reglas de espaciado, tipografía o color.
El gate (pnpm gate) ejecuta unas cuarenta comprobaciones sobre cada fixture del directorio fixtures/. Esto convierte la consistencia visual en una propiedad verificable por CI, no en una revisión manual. Alejandro Sánchez, CEO de 4Geeks Academy, le pidió a Mikati que documentara la herramienta: "amazing man, do you want to clone the 4geeks website and try to put it inside an article??" — Slack #blogequipo, 26 de agosto de 2026. Mikati respondió que el repositorio ya incluía benchmarks y estaba listo para publicarse en npm.
Qué tipos de diagrama soporta y cómo se animan
GeekChart soporta flowcharts, state diagrams, class diagrams, ER diagrams, sequence diagrams, gantt, timeline, journey, quadrant, radar, XY charts, sankey, treemap, kanban, pie charts, mindmaps y git graphs. Un único renderer dibuja todos los tipos, lo que elimina la fragmentación de estilos entre diagramas diferentes.
El pipeline de renderizado sigue seis pasos: paste (pegar el código Mermaid), repair (corrección automática), which diagram (detección de tipo), mermaid parses (el parser original genera el AST), we place (layout propio con ELK para árboles y serpentina propia para cadenas que saltan línea), we draw (cajas de tamaño fijo en grid de 8, líneas finas, un solo acento en el camino principal), y motion (animación con ritmo de pausa tras cada secuencia).
Las reglas numéricas viven en DESIGN.md y en packages/core/src/tokens.ts. El lienzo mide como máximo 1000 unidades de ancho (1200 para tableros), se adapta al contenido con padding de 48 unidades, y nunca baja de 480. La tipografía se mantiene a 11 unidades en relación 1:1 con los píxeles reales, lo que evita que el texto se vuelva ilegible en contenedores estrechos.
Instalación y uso del componente React
El componente React se instala con npm install geekchart o pnpm add geekchart. Para usarlo en una aplicación Next.js o React estándar:
import { GeekChart } from 'geekchart/react';
function MiPagina() {
const diagrama = `
flowchart TD
A[Inicio] --> B{Decision}
B -->|Sí| C[Proceso A]
B -->|No| D[Proceso B]
`;
return <GeekChart source={diagrama} />;
}El componente carga el parser de forma diferida en el primer uso. Esto significa que el bundle inicial no incluye el peso del parser de Mermaid; solo se descarga cuando el visitante necesita renderizar un diagrama. Para sitios con mucho tráfico y pocos diagramas, esto reduce el tiempo de carga interactiva (TTI) respecto a importar Mermaid directamente.
Los desarrolladores que buscan profundizar en el ecosistema React y herramientas de visualización pueden explorar el programa de Ingeniería IA para desarrolladores de 4Geeks Academy, donde se trabaja con componentes avanzados y renderizado server-side.
Renderizado server-side para sitios estáticos
Para blogs generados en build time o documentación técnica, GeekChart expone renderToHtml(source) desde geekchart/server. Esta función devuelve SVG inline sin JavaScript, lo que elimina el coste de runtime para el lector.
import { renderToHtml } from 'geekchart/server';
const svgEstatico = await renderToHtml(`
sequenceDiagram
Usuario->>API: POST /datos
API->>BD: INSERT
BD-->>API: OK
API-->>Usuario: 201 Created
`);
// svgEstatico contiene el SVG completo listo para insertar en HTMLEl SVG resultante incluye las animaciones como SMIL (Synchronized Multimedia Integration Language), compatibles con la mayoría de navegadores modernos. Para casos donde el soporte SMIL es problemático, el CLI ofrece exportación a MP4.
Esta aproximación de renderizado híbrido —server para contenido estático, cliente para interactividad— es la misma que se enseña en los bootcamps de desarrollo full stack de 4Geeks, donde los estudiantes aprenden a optimizar el bundle de aplicaciones React.
CLI para exportación estática y CI
El ejecutable de línea de comandos (npx geekchart) permite generar componentes React autónomos o archivos SVG/PNG/MP4 desde archivos .mmd:
# Generar componente React
npx geekchart diagrama.mmd -o Diagrama.tsx
# Exportar SVG estático
npx geekchart diagrama.mmd -o diagrama.svg
# Generar PNG para documentos
npx geekchart diagrama.mmd -o diagrama.png --width 1200Esta capacidad resulta útil en pipelines de documentación donde los diagramas deben versionarse como archivos binarios o incluirse en PDFs. El CLI incluye las mismas comprobaciones del gate, por lo que un diagrama que falla el diseño no llega a producción.
Benchmarks y rendimiento
El repositorio incluye un script de benchmark (pnpm bench) que mide tiempos de renderizado y tamaños de salida. Según el código disponible en packages/cli/scripts/bench.mjs, las pruebas ejecutan cada diagrama de referencia contra tres métricas: tiempo de parseo, tiempo de layout, y peso del SVG generado.
Comparado con Recharts 2.15 y Nivo 0.88 (librerías estándar de React para gráficos), GeekChart ocupa un nicho diferente: no compite en volumen de datos (donde Canvas supera a SVG), sino en claridad comunicativa de diagramas de flujo y arquitectura. Para datasets menores a 100 nodos, el overhead de SVG es despreciable frente a la mejora en percepción visual que aporta la animación secuenciada.
Los benchmarks de rendimiento en aplicaciones React son una habilidad clave para los ingenieros de IA, que deben optimizar la latencia de interfaces que consumen modelos de lenguaje.
Qué diferencia a GeekChart de otras soluciones
| Característica | GeekChart | Mermaid CLI | react-x-mermaid | Framer Motion + SVG |
|---|---|---|---|---|
| Sintaxis de entrada | Mermaid | Mermaid | Mermaid | Código React |
| Animación integrada | Sí (Manim-style) | Limitada (CSS manual) | No | Sí (a medida) |
| Consistencia visual garantizada | Sí (gate automático) | No | No | No |
| Server-side rendering | Sí | Sí (SVG estático) | Parcial | No |
| CLI para exportación | Sí | Sí (mmdc) | No | No |
| Bundle size (cliente) | Diferido (parser lazy) | N/A | Completo | Variable |
La diferencia clave es el gate de diseño. Mientras otras herramientas delegan la consistencia visual al autor, GeekChart la convierte en una propiedad testeable. Esto resulta crítico en equipos donde múltiples personas crean diagramas para documentación pública.
Casos de uso reales donde brilla
-
Documentación técnica de APIs: Un diagrama de secuencia que muestra el flujo de autenticación OAuth2, animado paso a paso, reduce el tiempo de comprensión respecto a una imagen estática. La sintaxis Mermaid permanece editable en Git, manteniendo el historial de versiones.
-
Posts de blog con arquitectura de sistemas: Los diagramas de componentes explican mejor cuando las conexiones aparecen en orden de dependencia. GeekChart permite generar el SVG en build time con
renderToHtml, evitando JavaScript en el cliente para contenido que no cambia. -
Presentaciones y vídeos: La exportación a MP4 convierte cualquier diagrama en recurso para contenido social o formación. El vocabulario de animación de Manim (pausas, apariciones secuenciales) está optimizado para retención de atención.
Limitaciones y cuándo NO usarlo
GeekChart no es la elección correcta para dashboards de datos en tiempo real ni para visualizaciones con miles de nodos. SVG se vuelve pesado cuando el DOM supera los 5.000 elementos, y la animación secuencial de Manim ralentiza la navegación si se aplican docenas de diagramas en la misma página.
Para gráficos de líneas con actualización continua (precios de bolsa, métricas de servidor), librerías basadas en Canvas como Chart.js o librerías de visualización de datos como D3.js ofrecen mejor rendimiento. GeekChart gana cuando la prioridad es comunicar estructura y flujo, no explorar datasets masivos.
Cómo contribuir y ampliar la librería
El repositorio está organizado en paquetes independientes: core contiene el renderer, react el wrapper de componente, cli las herramientas de línea de comandos, y geekchart el paquete publicado que agrupa todo. Para añadir un nuevo tipo de diagrama, se modifica el detector en packages/core, se implementa el layout específico, y se añade un fixture de prueba en fixtures/.
Las reglas de diseño se escriben en DESIGN.md y se codifican en packages/core/src/rules.ts. Cada regla nueva debe incluirse en el gate (packages/cli/scripts/gate.mjs) para garantizar que futuras contribuciones no degraden la consistencia visual. MIT licensed.
Preguntas frecuentes
¿GeekChart reemplaza a Mermaid.js? No. GeekChart usa el parser de Mermaid para generar el AST inicial, pero reemplaza el renderizado y añade animación propia. Necesitas conocer sintaxis Mermaid para usar GeekChart.
¿Funciona en proyectos Next.js 15 con App Router?
Sí. La función renderToHtml se ejecuta en Server Components o en generateStaticParams. El componente cliente se importa con dynamic() si necesitas interacción en el navegador.
¿Puedo personalizar los colores para mi marca?
El sistema de tokens en packages/core/src/tokens.ts permite sobreescribir la paleta, pero el gate de diseño valida que los contrastes y espaciados sigan cumpliendo las reglas de legibilidad.
¿Cuál es el tamaño del bundle añadido? El parser se carga bajo demanda. El bundle inicial solo incluye el wrapper React (unos 3 KB comprimidos). El parser completo se descarga una vez por visitante, en un chunk separado.
¿Soporta exportación a PowerPoint o PDF?
El CLI genera PNG y SVG, que PowerPoint importa directamente. Para PDF, el SVG vectorial mantiene la calidad a cualquier escala. No hay exportación nativa a .pptx.
¿Está disponible en npm? Según la conversación en Slack del 26 de agosto de 2026, el paquete está "primed for publishing on npm". Verifica la disponibilidad actual en npmjs.com/package/geekchart.