shieldcn AGENTS.md

AGENTS.md — shieldcn

What this is

shieldcn is a Turborepo monorepo that serves styled SVG/PNG badge images for use in GitHub READMEs, npm pages, and docs sites. It's a shields.io alternative where badges are rendered as actual shadcn/ui Button components via Satori.

Monorepo Structure

shieldcn/
├── packages/
│   ├── core/          ← @shieldcn/core — shared badge engine library
│   ├── web/           ← @shieldcn/web — marketing site (Vercel)
│   └── engine/        ← @shieldcn/engine — self-hosted Docker image
├── turbo.json
├── pnpm-workspace.yaml
└── ...

packages/core (@shieldcn/core)

Shared badge engine consumed by both web and engine. No build step — raw TypeScript consumed via transpilePackages.

• Badge renderer (src/badges/render.tsx) — React components → SVG via Satori. Uses Inter Medium font. Every badge goes through one resolve() function then one renderSingle() or renderSplit() function. No variant-specific render paths.
• Button tokens (src/badges/button-tokens.ts) — Exact shadcn Button design tokens (bg, fg, border per variant) resolved to hex values for both dark and light mode.
• Icon resolution (src/badges/simple-icons.ts) — Two sources: SimpleIcons (2400+) and React Icons (40,000+). Prefix convention: bare slug = SimpleIcons, ri:ComponentName = React Icons.
• Data providers (src/providers/) — npm, GitHub, Discord, Reddit, static badges, dynamic JSON, HTTPS endpoint, memo badges. Each returns { label, value, color?, link? }.
• Token pool (src/token-pool.ts) — GitHub OAuth token pool stored in Postgres. Distributes API requests across many user-donated tokens to stay under rate limits.
• Route handler (src/route-handler.ts) — Reusable handleBadgeGET() / handleBadgePUT() that parses URLs, fetches data, resolves icons/colors/variants, renders SVG/PNG/JSON. Accepts optional onTrack callback for analytics.
• Cache (src/cache.ts) — Two-tier caching (in-memory LRU + optional Upstash Redis) with per-provider backoff and rate budgets.
• Format (src/format.ts) — formatCount() number formatting (single source of truth).