Beautiful README badges.
A shields.io alternative styled as shadcn/ui buttons. Never paywalled.
Homepage · Docs · API Reference
About
shieldcn is an open-source badge service by Justin Levine. Every badge is free, every endpoint is public, and that's not changing.
Badges are rendered as actual shadcn/ui Button components via Satori — same font (Inter), same border-radius, same padding, same color tokens per variant and size. Not "inspired by" — the real thing, as SVG.
Built with jal-co/ui components.
Usage
    
Supported providers
See the docs for full endpoint details, interactive sandboxes, and copy-paste examples.
Package registries
| Provider | Badges | Endpoint |
|---|---|---|
| npm | version, downloads, license, node, types, dependents | /npm/{package} |
| PyPI | version, downloads, license, python version | /pypi/{package} |
| Crates.io | version, downloads, license | /crates/{crate} |
| Docker Hub | pulls, stars, version, image size | /docker/pulls/{image} |
| Packagist | version, downloads, license | /packagist/v/{vendor}/{package} |
| RubyGems | version, downloads, license | /rubygems/{gem} |
| NuGet | version, downloads | /nuget/{package} |
| Pub.dev | version, likes, points, popularity | /pub/{package} |
| Homebrew | version (formula + cask), installs, downloads | /homebrew/{formula} |
| Maven Central | version | /maven/{groupId}/{artifactId} |
| CocoaPods | version | /cocoapods/{pod} |
| JSR | version, score | /jsr/{@scope}/{name} |
| Bundlephobia | min size, minzip size, tree-shaking | /bundlephobia/minzip/{package} |
| Conda | version, downloads, platform | /conda/v/{channel}/{package} |
| jsDelivr | CDN hits, rank | /jsdelivr/hits/npm/{package} |
| Chocolatey | version, downloads | /chocolatey/v/{package} |
| Snapcraft | version | /snapcraft/v/{snap} |
Code platforms
| Provider | Badges | Endpoint |
|---|---|---|
| GitHub | stars, forks, watchers, license, release, CI, checks, issues, PRs, milestones, commits, downloads (all/specific asset, all/latest/tag), dependabot, and more | /github/{owner}/{repo}/{topic} |
| GitLab | stars, forks, issues, pipeline, license, release, contributors | /gitlab/{owner}/{repo}/{topic} |
| Codecov | coverage percentage (color-coded) | /codecov/{service}/{owner}/{repo} |
| Coveralls | coverage percentage (color-coded) | /coveralls/{service}/{owner}/{repo} |
| SonarCloud | quality gate, bugs, vulnerabilities, coverage, maintainability, reliability, security | /sonar/{topic}/{component} |
| VS Code Marketplace | installs, rating, version | /vscode/installs/{publisher}/{extension} |
| Open VSX | version, downloads, rating | /openvsx/v/{namespace}/{extension} |
App stores
| Provider | Badges | Endpoint |
|---|---|---|
| Chrome Web Store | version, users, rating | /chrome/v/{extensionId} |
| Mozilla Add-ons | version, users, rating, downloads | /amo/v/{slug} |
| Flathub | version, downloads | /flathub/v/{appId} |
| F-Droid | version | /fdroid/v/{appId} |
Social & Community
| Provider | Badges | Endpoint |
|---|---|---|
| Discord | online count, members | /discord/{serverId} |
| karma, subscribers | /reddit/subscribers/r/{subreddit} |
|
| Bluesky | followers, following, posts | /bluesky/{handle} |
| YouTube | subscribers, channel views, video views, likes, comments | /youtube/subscribers/{channelId} |
| Mastodon | followers, following, posts | /mastodon/followers/{instance}/{acct} |
| Lemmy | subscribers, posts, comments | /lemmy/subscribers/{instance}/{community} |
| Hacker News | karma | /hackernews/{userId} |
| Twitch | live status, followers | /twitch/status/{login} |
| Discourse | topics, posts, users, likes | /discourse/topics/{server} |
| Matrix | room members | /matrix/members/{roomAlias} |
| Stack Exchange | tag questions, user reputation | /stackexchange/tag/{tag} |
Funding & Tools
| Provider | Badges | Endpoint |
|---|---|---|
| Open Collective | backers, sponsors, contributors, balance, budget | /opencollective/backers/{slug} |
| Liberapay | receiving, patrons, goal | /liberapay/receiving/{username} |
| WakaTime | coding time | /wakatime/{username} |
| Weblate | translation %, language count | /weblate/translation/{server}/{project}/{component} |
| Modrinth | downloads, followers, version, game versions | /modrinth/downloads/{slug} |
| Tokscale | tokens, cost, rank, active days | /tokscale/{username} |
Custom badges
| Type | Description | Endpoint |
|---|---|---|
| Static | Custom label/message/color | /badge/{label}-{message}-{color} |
| Dynamic JSON | Fetch any JSON API | /badge/dynamic/json?url=...&query=... |
| HTTPS Endpoint | Proxy any JSON endpoint | /https/{hostname}/{path} |
| Memo | User-stored badges (PUT API) | /memo/{key} |
Variants & sizes
Every badge supports shadcn Button variants and sizes:
         
Icons
Three icon libraries (40,000+ icons) plus custom SVG upload:
- Simple Icons —
?logo=react - React Icons —
?logo=ri:GoStarFill - React Icons —
?logo=ri:FaReact - Custom SVG —
?logo=data:image/svg+xml;base64,...— upload any SVG icon via the Badge Builder or encode it yourself
Response formats
.png— PNG image (recommended for GitHub READMEs and maximum compatibility).svg— SVG image (scalable, smaller file size).json— raw badge data/shields.json— shields.io-compatible endpoint
Both .png and .svg work everywhere GitHub renders images. Just swap the extension.
Design principles
- shadcn buttons, not shields.io rectangles — badges are rendered as actual shadcn Button components with real Inter font outlines via Satori
- Everything configurable — variant, size, mode, colors, icons, opacity, split, dot — but sensible defaults so you don't have to configure anything
- Shields.io compatible — same URL patterns for static/dynamic badges, same text encoding, shields.io JSON endpoint support
- Open source, never paywalled — every badge type, every variant, every icon source is free
Agent skill
Install the shieldcn skill to let AI coding agents (Claude Code, Cursor, Codex, and 40+ more) add badges to your projects:
npx skills add jal-co/shieldcn
Once installed, ask your agent to "add shieldcn badges to the README" — it knows all providers, URL patterns, and query parameters.
Learn more in the skill docs.
Self-Hosting
Run your own badge engine with Docker:
git clone https://github.com/jal-co/shieldcn.git cd shieldcn docker compose -f packages/engine/docker-compose.yml up -d # Test it curl http://localhost:3000/badge/self--hosted-green.svg
Or pull the pre-built image:
docker pull ghcr.io/jal-co/shieldcn/engine:latest
See the Self-Hosting Guide for full setup details.
Local Development
pnpm install # install all workspace deps pnpm dev:web # start the web site pnpm dev:engine # start the self-hosted engine pnpm build:web # build the web site pnpm build:engine # build the engine
The repo is a Turborepo monorepo with three packages:
packages/core— shared badge engine librarypackages/web— marketing site (Vercel)packages/engine— self-hosted Docker image
Token pool
shieldcn uses a token pool (inspired by shields.io) to distribute GitHub API requests across many tokens. You can help by authorizing the OAuth app — read-only, zero scopes, revocable anytime.
Credits
- shields.io — the original badge service. Inspiration for URL patterns, static badge format, and the token pool system.
- badgen.net — inspiration for many badge types and endpoint structures, especially the GitHub badge coverage.
- shadcn/ui — the design system these badges are built on.
- Satori — Vercel's JSX-to-SVG engine that makes rendering React components as badge images possible.
- jal-co/ui — the component library powering the docs site.
- @k33bs — creator of shieldcngen, the badge generator tool powering the
/genpage.
Contributing
PRs welcome. See AGENTS.md for architecture overview.
To add shadcn components: cd packages/web && pnpm dlx shadcn@latest add {component}