Anatomía de una URL de badge de shields.io
Los badges de shields.io siguen la estructura: https://img.shields.io/{tipo}/{parámetros}?{opciones}. El tipo determina la fuente de datos (github, npm, badge) y los parámetros varían según el tipo. Por ejemplo, un badge de GitHub actions usa /github/actions/workflow/status/usuario/repo/workflow.yml, mientras que un badge estático usa /badge/label-mensaje-color.
Las opciones de query string más útiles: style= (flat, flat-square, plastic, for-the-badge, social), logo= (nombre de simple-icons), logoColor= (hex sin #), label= (override del texto izquierdo), color= (hex o named como brightgreen, blue, red). Ejemplo completo: ?style=flat-square&logo=github&logoColor=white&label=build.
Para badges dinámicos (que consultan APIs), shields.io cachea resultados por 5 minutos normalmente. Podés forzar recarga agregando &cacheBuster=timestamp. Los badges estáticos son inmediatos porque no consultan nada externo. Si un badge tarda en cargar, probablemente la API externa esté lenta o el proyecto no existe con ese path exacto.
Estrategia de badges en README: cuáles incluir y cuáles evitar
Un README efectivo muestra 4-8 badges máximo en la parte superior: estado de build (crítico), cobertura de tests (si es +70%), versión actual, y licencia. Todo lo demás es secundario y puede ir en secciones específicas o se omite. Demasiados badges arriba crean 'banner blindness' y hacen que los visitantes ignoren todos.
Badges que SÍ agregan valor: build status (muestra si el proyecto funciona), coverage (indica calidad de tests), version (ayuda a saber si es estable), downloads/month (valida popularidad), last commit (indica actividad reciente), license (información legal clave). Badges que NO agregan valor real: 'made with love', badges de todos los lenguajes usados si son obvios del código, múltiples badges de lo mismo (no necesitás npm downloads diarios, semanales Y mensuales).
Para proyectos empresariales, priorizá badges de confiabilidad: uptime, security scanning (Snyk, Dependabot), compliance (SOC2, HIPAA si aplica). Para proyectos open source comunitarios, priorizá badges sociales: contributors, PRs welcome, Discord/chat. El contexto determina qué badges comunican seriedad versus accesibilidad.
Creación de badges personalizados: estáticos vs dinámicos
Badges estáticos usan la sintaxis: . Reemplazá espacios con %20 o guiones. Colores pueden ser hex (sin #) o nombres: brightgreen, green, yellowgreen, yellow, orange, red, blue, lightgrey, blueviolet, ff69b4. Ejemplo: /badge/coverage-85%25-brightgreen crea un badge que dice 'coverage 85%'.
Badges dinámicos con endpoint.json: shields.io puede consultar cualquier endpoint JSON público. Formato: . Tu endpoint debe devolver: {"schemaVersion":1,"label":"custom","message":"valor","color":"blue"}. Útil para métricas propias: usuarios activos, transacciones/día, latencia promedio. Implementá cache en tu lado para no saturar tu servidor.
Para badges de repositorios privados, algunos servicios requieren tokens. Shields.io soporta esto vía query params pero exponé el token públicamente en tu README. Mejor solución: generá el badge server-side en tu CI y subiló como artefacto, o usá servicios como Codecov que manejan repos privados con webhooks. No hardcodees tokens de acceso en URLs públicas nunca.
Automatización: generar badges en CI/CD
En tu workflow de GitHub Actions, generá badges de coverage automáticamente: después de correr tests con jest --coverage, usá una action como jest-coverage-badges que parsea coverage/coverage-summary.json y actualiza un badge SVG en el repo. Commitea el SVG y referencialo en el README como . Esto evita dependencias externas y funciona en repos privados.
Para badges de performance (bundle size, lighthouse scores), herramientas como bundlesize y lighthouse-ci pueden generar badges automáticamente. Ejemplo: corre Lighthouse en CI, extraé el score, postealo a un endpoint que devuelva JSON de shields.io, y referencialo en el README. El badge se actualiza en cada merge a main.
Errores frecuentes: olvidar actualizar los badges cuando cambiás el nombre del repo (las URLs quedan rotas), no configurar permisos para que el CI escriba en el repo (los badges no se actualizan), o generar badges en branches feature que nunca se mergean (nadie los ve). Configurá badges solo en la rama principal y hacé que el proceso sea parte del merge automáticamente usando branch protection rules.