🌐 English Version | 🇪🇸 Versión en Español
Generate dynamic and customizable SVG cards with your GitHub statistics to showcase your profile and projects.
GitHub Helpers is an open-source, production-grade microservice and web application built with TypeScript, NestJS, and Astro. It allows you to query real-time general stats, commit activity habits, streak counters, developer ranks, trophies, top repositories, and programming language distributions for any GitHub user, generating high-definition vector SVG cards ready to embed directly into your README.md.
Developed and maintained by CreativeCode.com.co.
Interactively customize and preview your cards in real time at:
👉 https://github-helpers.creativecode.com.co/
- Clean Architecture: Domain-Driven Design (DDD) with decoupled Domain, Use Cases, Adapters, and Infrastructure layers.
- Hot Rendering & Base64 Bypass: On-the-fly SVG generation with image Base64 embedding to ensure GitHub Camo proxy (
camo.githubusercontent.com) compatibility. - Comprehensive Card Suite:
- 📊 General Stats Card: Commits, stars, PRs, issues, and followers.
- 💻 Most Used Languages: Byte-weighted language distribution with custom legends.
- 📅 Commit Habit Heatmap Matrix: 7x24 weekly hourly commit distribution matrix.
- 🔥 Contribution Streak Counter: Current streak, longest streak, and active days.
- 🎖️ Developer Rank: Automated grade assignment (S+, A+, B, etc.).
- 🏆 GitHub Trophies: Earned milestone achievements.
- ⭐ Top Repositories & Featured Repo: Highlights for top starred projects.
- 💖 GitHub Sponsors Card: Monthly and one-time sponsor overview.
- 👁️ Profile Views Badge & Shields.io Badges: Real-time profile views tracker and custom SVG badges.
- GitHub App OAuth Integration: 1-click read-only authentication to aggregate private repositories and organization contributions.
- OWASP Compliant Security: Strict regex parameter validation, Helmet headers, IP rate limiting, and encrypted token management.
<!-- General Stats Card -->
<!-- Most Used Languages Card -->
<!-- Commit Activity Heatmap Matrix -->
<!-- Profile Views Badge -->
Genera tarjetas SVG dinámicas y personalizables con tus estadísticas de GitHub para destacar tu perfil y tus proyectos.
GitHub Helpers es un microservicio y cliente web desarrollado en Node.js con TypeScript, NestJS y Astro. Permite consultar en tiempo real las estadísticas generales, matriz de hábitos de commit, trofeos y la distribución de lenguajes de cualquier usuario de GitHub, generando tarjetas vectoriales (SVG) listas para incrustar directamente en tu archivo README.md.
Desarrollado y mantenido por CreativeCode.com.co.
Diseña y personaliza tus tarjetas interactivamente en:
👉 https://github-helpers.creativecode.com.co/
- Clean Architecture (Arquitectura Limpia): Estructurado en capas desacopladas (Dominio, Casos de Uso, Adaptadores e Infraestructura) para garantizar mantenibilidad, testabilidad y escalabilidad.
- API en Vivo (Hot Rendering): Generación de tarjetas SVG al vuelo a través de endpoints con cabeceras
Content-Type: image/svg+xml. - Caché en Memoria (2 horas): Minimiza las llamadas a la API de GitHub para evitar bloqueos por límite de tasa (Rate Limits) mediante el patrón Decorador.
- Imágenes Autocontenidas (Base64 Bypass): Las fotos de perfil se descargan y se convierten a Base64 en el servidor, garantizando que el proxy de imágenes de GitHub (
camo.githubusercontent.com) las muestre sin problemas. - Métricas Clave de Visibilidad:
- Estadísticas Generales: Commits totales, estrellas obtenidas, pull requests, issues y seguidores.
- Lenguajes más Usados: Gráfica de distribución de lenguajes (calculada por peso de bytes) con leyenda estructurada.
- Matriz de Hábitos de Commit: Grilla semanal 7x24 de distribución horaria de commits.
- Racha de Contribuciones & Rango: Cálculo automático de racha activa y grado de desarrollador (S+, A+, B, etc.).
- Trofeos y Repositorios Destacados: Hitos alcanzados y tarjetas de proyectos top.
- Perfil de GitHub Sponsors: Resumen de patrocinadores mensuales y de pago único, estimación de ingresos y grid interactivo de patrocinadores.
- Insignias SVG estilo Shields.io: Badges dinámicos personalizables para visitas de perfil y rango.
- Autenticación Directa con GitHub App: Conexión transparente mediante GitHub OAuth con soporte de Refresh Tokens automáticos y permisos de solo lectura de metadata para sumar repositorios privados y organizaciones.
- Panel de Métricas del Usuario & GDPR: Permite a cada usuario autenticado consultar sus propias métricas personales (visitas de perfil y renders de tarjetas) y realizar la eliminación permanente de su cuenta y datos en cualquier momento.
- Múltiples Temas Estéticos: Dark, Light, Neon, Solarized, Radical, Tokyonight y Glassmorphism.
- Panel Web Premium (Glassmorphism): Una interfaz web elegante construida en CSS puro con vista previa en tiempo real y copiador de enlaces Markdown automático.
- Generador de README.md de Ejemplo: Genera automáticamente una plantilla Markdown completa con el saludo al usuario y todas las tarjetas cargadas con éxito.
- Guía Integrada para Perfil de GitHub: Tutorial paso a paso en
/help#github-profilepara crear el repositorio especialusername/usernamey desplegar las métricas. - Pruebas Unitarias Integradas: Implementadas utilizando Vitest con inyección de dependencias.
- Listo para Docker y Coolify: Dockerfile de construcción en múltiples etapas (multi-stage) optimizado para producción.
El código fuente está organizado siguiendo los principios de Clean Architecture:
src/
├── domain/ # Lógica de negocio pura (Entidades y Contratos de Repositorios)
│ ├── entities/ # UserStats, LanguageStat, Metrics, UserToken, Validation
│ └── repositories/ # IGitHubRepository, ITokenRepository, IMetricsRepository
├── use-cases/ # Casos de uso (Orquestadores de la lógica de negocio)
│ ├── cards/ # GetUserStatsCardUseCase, GetUserLanguagesCardUseCase, etc.
│ └── tokens/ # RegisterUserTokenUseCase, RevokeUserTokenUseCase
├── adapters/ # Adaptadores de Interfaz (Controladores, Repositorios y Presentadores)
│ ├── controllers/ # CardController, TokenController, MetricsController
│ ├── presenters/ # statsCard, languagesCard, commitActivityCard, badge.presenter (Renderizadores SVGs)
│ └── repositories/ # TypeORMTokenRepository, TypeORMMetricsRepository, ApiGitHubRepository, CachedGitHubRepository
└── infrastructure/ # Detalles técnicos concretos (Base de datos, Servidor Express/Fastify, Criptografía)
├── database/ # Configuración de TypeORM con PostgreSQL y Entidades
│ └── entities/ # Entidades de base de datos (GlobalMetric, UserMetric, etc.)
├── express/ # Enrutamiento, middlewares y arranque de servidor
├── security/ # Criptografía AES-256-GCM y validación de scopes
└── server.ts # Entrypoint principal
El proyecto utiliza alias @/ apuntando al directorio src/. Esto previene la existencia de rutas relativas complejas como ../../.
- En desarrollo: Se resuelve en tiempo de ejecución utilizando
tsconfig-paths/register. - En producción:
tsc-aliasreescribe los imports a rutas relativas nativas durante la compilación en el directoriodist/.
- Node.js v18 o superior.
- Gestor de paquetes pnpm (exclusivo del repositorio).
- (Opcional) Un token de acceso personal (PAT) de GitHub para aumentar el límite de peticiones de la API.
- Clona e ingresa al repositorio.
- Instala las dependencias estables usando
pnpm:pnpm install
- Copia el archivo de configuración de entorno:
cp .env.example .env
- Abre el archivo
.envy configura las siguientes variables clave:GITHUB_TOKEN: Tu token de acceso personal de GitHub para evitar límites de tasa.METRICS_KEY: Clave secreta obligatoria para poder acceder a los endpoints de analíticas (/api/metrics).TRUST_PROXY: Número de saltos del proxy (por defecto1), útil para que el rate limit identifique correctamente las IPs detrás de Cloudflare, Nginx, etc.PRIVATE_STATS_COMING_SOON: Estado de configuración de estadísticas privadas. Establécelo enfalsepara habilitar y activar completamente la funcionalidad de registro/revocación de tokens (por defectotrue).STATS_HISTORY_FREQUENCY_HOURS: Frecuencia mínima en horas entre tomas de instantáneas del historial de estadísticas del usuario (por defecto12).
- Modo Desarrollo (auto-reload y resolución de paths):
pnpm dev
- Ejecutar Pruebas Unitarias (Vitest):
pnpm test - Compilar para Producción (compila archivos TS y reescribe alias):
pnpm build
- Iniciar Servidor Compilado:
pnpm start
- Gestionar Versiones y Releases (release-it):
pnpm release
Una vez ejecutado, el panel de configuración estará disponible en:
👉 http://localhost:3000
Las tarjetas se pueden incrustar en cualquier archivo Markdown usando la siguiente sintaxis:
| Endpoint | Descripción | Ejemplo de Uso |
|---|---|---|
/api/stats |
Estadísticas generales (commits, PRs, estrellas, seguidores) |  |
/api/languages |
Gráfico de distribución de lenguajes |  |
/api/commit-activity |
Matriz semanal 7x24 de hábitos de commit |  |
/api/streak |
Racha de contribuciones activas y récords |  |
/api/rank |
Tarjeta de grado / rango de desarrollador (S+, A+, B) |  |
/api/trophies |
Trofeos e hitos alcanzados en GitHub |  |
/api/top-repos |
Tarjeta con los repositorios más destacados |  |
/api/sponsors |
Tarjeta del perfil de GitHub Sponsors |  |
/api/badge |
Insignia SVG estilo Shields.io / Contador de visitas |  |
username(Obligatorio): Nombre de usuario u organización en GitHub. Valida con regex/^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$/i.theme(Opcional):dark(por defecto),light,neon,glassmorphism,solarized,radical,tokyonight.localeolang(Opcional):es(Español, por defecto) oen(Inglés). Traduce dinámicamente los textos internos de la tarjeta.
El servicio cuenta con una interfaz web segura de analíticas en la dirección /admin/metrics.
- Acceso: Protegido mediante un formulario de autenticación glassmorphic que valida contra la clave configurada en la variable de entorno
METRICS_KEY. - Analíticas en Tiempo Real:
- Métricas KPI para renderizados totales, usuarios únicos registrados y vistas de insignias de perfil.
- Gráfico de dona (Doughnut) de distribución de tipos de tarjetas solicitadas.
- Gráfico de barras apiladas (Stacked Bar) de tráfico por origen (GitHub Camo vs Web Directa).
- Listado de usuarios/perfiles más activos con fecha de última actualización y hits de perfil.
Este microservicio implementa las siguientes medidas de seguridad para entornos de producción:
- Cabeceras Seguras (Helmet): Configurado con políticas de recursos de origen cruzado (
cross-origin) para permitir incrustar de forma segura las tarjetas en READMEs externos. - Rate Limiting: Límite de 100 peticiones cada 15 minutos por dirección IP. En caso of bloqueo, responde con un SVG legible para evitar errores de renderizado de imágenes.
- Validación de Parámetros por Expresión Regular:
- Validado a nivel de Controller y en la capa de negocio de Use Cases.
- Username:
/^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$/i - Repo:
/^[a-z\d-_.]{1,100}$/i
- Secure by Default: Los endpoints de métricas se bloquean por defecto con error
403si no se configura la variableMETRICS_KEY.
Para obtener información detallada sobre reporte responsable de vulnerabilidades y políticas de parches, consulta nuestra Política de Seguridad (SECURITY.md).
Si este proyecto te resulta útil para personalizar tu perfil de GitHub o tus repositorios, puedes apoyar su desarrollo y mantenimiento continuo a través de GitHub Sponsors:
👉 https://github.com/sponsors/joaltoroc
Consulta nuestra Guía de Contribución (CONTRIBUTING.md) para conocer las normas de estilo, la arquitectura del proyecto y cómo enviar un Pull Request.
Este proyecto está bajo la licencia MIT.
Este proyecto incluye un Dockerfile optimizado con builds en multi-etapa y configuración segura que se ejecuta bajo el usuario no root node.
- Crea un nuevo recurso de tipo Application en tu panel de Coolify.
- Selecciona GitHub Repository como fuente y apunta a este repositorio.
- En la configuración de construcción, selecciona Dockerfile.
- Configura el puerto de exposición en el puerto
3000. - Base de Datos: Añade un servicio de base de datos PostgreSQL en Coolify.
- Variables de Entorno: Agrega los datos de acceso de la base de datos y tus tokens de seguridad:
DB_HOST,DB_PORT,DB_DATABASE,DB_USERNAME,DB_PASSWORD,GITHUB_TOKEN,METRICS_KEY,TRUST_PROXY.
- Haz clic en Deploy. Coolify construirá el contenedor seguro de producción y lo pondrá en marcha con SSL automático.