Why I built shieldcn
I use badges on every repo I publish. Stars, license, version, CI status. They're useful. They also look like they were designed in 2013, because they were.
shields.io is an incredible project and I don't want to take anything away from it. It powers most of the badges you see on GitHub. But every time I'd set up a new README, I'd drop in these flat colored rectangles next to a project that uses shadcn/ui, Tailwind, Inter font, proper spacing, and they'd just look... off. Like putting a bumper sticker on a car you actually care about.
So I built shieldcn.
What it actually is
shieldcn renders badges as real shadcn/ui Button components. Not "inspired by" or "styled to look like." The actual component, rendered server-side through Satori and output as SVG or PNG. Same Inter font with proper outlines, same border-radius, same padding, same color tokens per variant and size.
You get all the shadcn Button variants (default, secondary, outline, ghost, destructive, branded) and all the sizes (xs, sm, default, lg). Every badge supports 40,000+ icons across Simple Icons and React Icons, or you can upload your own SVG.
The URL pattern is straightforward:
If you already use shields.io, swap the domain and your URLs mostly just work. There's a migration tool on the site and the CLI can do it automatically.
The CLI
I wanted this to be zero-friction. So there's a CLI:
npx shieldcn-cli
Run it in your repo and it scans your package.json, detects your GitHub remote, figures out what badges make sense, and generates the markdown. You can pipe it straight into your README with --inject. If you're migrating from shields.io, npx shieldcn-cli migrate rewrites your existing badge URLs.
Self-hosting
The badge engine runs as a Docker container. Clone the repo, docker compose up, and you've got your own instance. I wanted people to be able to run this on their own infrastructure if they wanted to, not just depend on my Vercel deployment. The whole project is a Turborepo monorepo with three packages: core (shared badge logic), web (the marketing site), and engine (the Docker image).
The agent skill
This was a fun one. shieldcn ships as an agent skill that you can install in Claude Code, Cursor, Codex, or any of the 40+ agents that support the skills spec:
npx skills add jal-co/shieldcn
Once installed, you can just tell your agent "add shieldcn badges to the README" and it knows all the providers, URL patterns, and query parameters. It writes the markdown for you. I've been using it on my own repos and it's genuinely faster than doing it by hand.
Why open source, why free
Every badge type, every variant, every icon source is free. I'm not going to paywall badge styles or providers. Same promise I made with jal-co/ui: open source, MIT license, never paywalled.
The project hit 137 stars and picked up 7 forks in its first few weeks. People are using it, contributing providers, and building tools on top of it (like shieldcngen, a community-built badge generator that now powers the /gen page on the site).
If you want to try it: shieldcn.dev. If you want to contribute: github.com/jal-co/shieldcn. If you want to complain about your current badges being ugly, I'm on X.
Till next time,
Justin