https://github.com/jal-co/shieldcn
Beautiful README badges, inspired by shields.io and styled like shadcn/ui.
https://github.com/jal-co/shieldcn
agent-skills badges badges-markdown markdown open-source readme readme-badges shadcn-ui shields shields-io shields-io-badges
Last synced: 13 days ago
JSON representation
Beautiful README badges, inspired by shields.io and styled like shadcn/ui.
- Host: GitHub
- URL: https://github.com/jal-co/shieldcn
- Owner: jal-co
- License: mit
- Created: 2026-04-22T22:16:53.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-27T02:46:34.000Z (17 days ago)
- Last Synced: 2026-05-27T04:26:06.791Z (17 days ago)
- Topics: agent-skills, badges, badges-markdown, markdown, open-source, readme, readme-badges, shadcn-ui, shields, shields-io, shields-io-badges
- Language: TypeScript
- Homepage: https://shieldcn.dev
- Size: 2.78 MB
- Stars: 247
- Watchers: 0
- Forks: 12
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
Beautiful README badges.
A shields.io alternative styled as shadcn/ui buttons. Never paywalled.
Homepage ยท Docs ยท CLI ยท API Reference ยท ๐
## About
shieldcn is an open-source badge service by [Justin Levine](https://justinlevine.me). Every badge is free, every endpoint is public, and that's not changing.
Badges are rendered as actual [shadcn/ui](https://ui.shadcn.com) Button components via [Satori](https://github.com/vercel/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](https://ui.justinlevine.me) components.
## CLI
Generate badges from your terminal:
```bash
# Scan current repo and generate badge markdown
npx shieldcn-cli
# Scan a GitHub repo
npx shieldcn-cli vercel/next.js --variant branded
# Inject badges into README
npx shieldcn-cli --inject
# Migrate shields.io URLs to shieldcn
npx shieldcn-cli migrate
```
See the [CLI docs](https://shieldcn.dev/docs/cli) for full usage.
## Usage
```md
```
### Badge groups
Combine multiple badges into a single joined image โ like a [shadcn ButtonGroup](https://ui.shadcn.com/docs/components/radix/button-group):
```md
```
Join any badge paths with `+` under `/group/`. Query params apply to all segments. See the [Badge Group docs](https://shieldcn.dev/docs/badges/group).
### Animated badges
Add `?animate=pulse`, `glow`, or `shimmer` to bring a badge to life:
- **`pulse`** / **`glow`** animate the status dot (great for live, CI, or "online" badges)
- **`shimmer`** sweeps a highlight across the whole badge
For `.svg` badges the animation is pure CSS โ no JavaScript โ and automatically goes static for visitors with reduced motion enabled. Because GitHub sanitizes animated SVGs, request the **`.gif`** extension to animate inside a GitHub README:
```md
```
See the [API reference](https://shieldcn.dev/docs/api-reference) for the full list of animation options.
## Supported providers
See the [docs](https://shieldcn.dev/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}` |
| **Reddit** | karma, subscribers | `/reddit/subscribers/r/{subreddit}` |
| **Bluesky** | followers, following, posts | `/bluesky/{handle}` |
| **X / Twitter** | follow CTA, mention CTA | `/x/follow/{username}` |
| **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 |
|------|-------------|----------|
| **Badge Group** | Multiple badges joined in one image | `/group/{badge1}+{badge2}+{badge3}` |
| **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:
```md
```
## Icons
Three icon libraries (40,000+ icons) plus custom SVG upload:
- **[Simple Icons](https://simpleicons.org)** โ `?logo=react`
- **[React Icons](https://react-icons.github.io/react-icons/)** โ `?logo=ri:GoStarFill`
- **[React Icons](https://react-icons.github.io/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](https://github.com/vercel-labs/skills#supported-agents)) add badges to your projects:
```bash
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](https://shieldcn.dev/docs/skill).
## Self-Hosting
Run your own badge engine with Docker:
```bash
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:
```bash
docker pull ghcr.io/jal-co/shieldcn/engine:latest
```
See the [Self-Hosting Guide](https://shieldcn.dev/docs/self-hosting) for full setup details.
## Local Development
```bash
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 library
- `packages/web` โ marketing site (Vercel)
- `packages/engine` โ self-hosted Docker image
## Token pool
shieldcn uses a [token pool](https://shieldcn.dev/token-pool) (inspired by [shields.io](https://shields.io/blog/2024-11-14-how-shields-io-uses-the-github-api)) 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](https://shields.io)** โ the original badge service. Inspiration for URL patterns, static badge format, and the token pool system.
- **[badgen.net](https://badgen.net)** โ inspiration for many badge types and endpoint structures, especially the GitHub badge coverage.
- **[shadcn/ui](https://ui.shadcn.com)** โ the design system these badges are built on.
- **[Satori](https://github.com/vercel/satori)** โ Vercel's JSX-to-SVG engine that makes rendering React components as badge images possible.
- **[jal-co/ui](https://ui.justinlevine.me)** โ the component library powering the docs site.
- **[@k33bs](https://github.com/k33bs)** โ creator of [shieldcngen](https://github.com/k33bs/shieldcngen), the badge generator tool powering the [`/gen`](https://shieldcn.dev/gen) page.
## Contributing
PRs welcome. See [AGENTS.md](./AGENTS.md) for architecture overview.
To add shadcn components: `cd packages/web && pnpm dlx shadcn@latest add {component}`
## License
[MIT](./LICENSE)