{"id":49869505,"url":"https://github.com/jal-co/shieldcn","last_synced_at":"2026-05-31T05:02:47.815Z","repository":{"id":353416341,"uuid":"1218446841","full_name":"jal-co/shieldcn","owner":"jal-co","description":"Beautiful README badges, inspired by shields.io and styled like shadcn/ui.","archived":false,"fork":false,"pushed_at":"2026-05-27T02:46:34.000Z","size":2910,"stargazers_count":247,"open_issues_count":0,"forks_count":12,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T04:26:06.791Z","etag":null,"topics":["agent-skills","badges","badges-markdown","markdown","open-source","readme","readme-badges","shadcn-ui","shields","shields-io","shields-io-badges"],"latest_commit_sha":null,"homepage":"https://shieldcn.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jal-co.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"jal-co","ko_fi":"jalco","open_collective":"shieldcn"}},"created_at":"2026-04-22T22:16:53.000Z","updated_at":"2026-05-27T02:46:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jal-co/shieldcn","commit_stats":null,"previous_names":["jal-co/shieldcn"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jal-co/shieldcn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jal-co%2Fshieldcn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jal-co%2Fshieldcn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jal-co%2Fshieldcn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jal-co%2Fshieldcn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jal-co","download_url":"https://codeload.github.com/jal-co/shieldcn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jal-co%2Fshieldcn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33719601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","badges","badges-markdown","markdown","open-source","readme","readme-badges","shadcn-ui","shields","shields-io","shields-io-badges"],"created_at":"2026-05-15T05:00:37.421Z","updated_at":"2026-05-31T05:02:47.802Z","avatar_url":"https://github.com/jal-co.png","language":"TypeScript","funding_links":["https://github.com/sponsors/jal-co","https://ko-fi.com/jalco","https://opencollective.com/shieldcn"],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://shieldcn.dev\"\u003e\n    \u003cimg src=\"./packages/web/brand/repo-header.png\" alt=\"shieldcn\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Beautiful README badges.\u003cbr /\u003e\n  A \u003ca href=\"https://shields.io\"\u003eshields.io\u003c/a\u003e alternative styled as \u003ca href=\"https://ui.shadcn.com\"\u003eshadcn/ui\u003c/a\u003e buttons. Never paywalled.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://shieldcn.dev\"\u003eHomepage\u003c/a\u003e · \u003ca href=\"https://shieldcn.dev/docs\"\u003eDocs\u003c/a\u003e · \u003ca href=\"https://shieldcn.dev/docs/cli\"\u003eCLI\u003c/a\u003e · \u003ca href=\"https://shieldcn.dev/docs/api-reference\"\u003eAPI Reference\u003c/a\u003e · \u003ca href=\"https://x.com/jalcowastaken\"\u003e𝕏\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://shieldcn.dev/group/github/stars/jal-co/shieldcn%2Bgithub/license/jal-co/shieldcn%2Bgithub/contributors/jal-co/shieldcn%2Bgithub/last-commit/jal-co/shieldcn.svg?variant=branded\" alt=\"shieldcn stats\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://shieldcn.dev/docs/self-hosting\"\u003e\u003cimg src=\"https://shieldcn.dev/badge/host%20with-docker-2496ED.svg?variant=branded\u0026logo=docker\" alt=\"host with docker\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://openpanel.dev?ref=justinlevine.me\"\u003e\u003cimg src=\"https://shieldcn.dev/badge/analytics%20by-openpanel.svg?variant=branded\u0026logo=openpanel\" alt=\"analytics by openpanel\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://shadcncraft.com?utm_source=shieldcn.dev\"\u003e\u003cimg src=\"https://shieldcn.dev/badge/built%20with-shadcncraft-171717.svg?logo=shadcncraft\u0026logoColor=fff\u0026variant=branded\" alt=\"built with shadcncraft\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.shadcnblocks.com?utm_source=shieldcn.dev\"\u003e\u003cimg src=\"https://shieldcn.dev/badge/built%20with-shadcnblocks-000000.svg?logo=shadcnblocks\u0026logoColor=fff\u0026variant=branded\" alt=\"built with shadcnblocks\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## About\n\nshieldcn 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.\n\nBadges 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.\n\nBuilt with [jal-co/ui](https://ui.justinlevine.me) components.\n\n## CLI\n\nGenerate badges from your terminal:\n\n```bash\n# Scan current repo and generate badge markdown\nnpx shieldcn-cli\n\n# Scan a GitHub repo\nnpx shieldcn-cli vercel/next.js --variant branded\n\n# Inject badges into README\nnpx shieldcn-cli --inject\n\n# Migrate shields.io URLs to shieldcn\nnpx shieldcn-cli migrate\n```\n\nSee the [CLI docs](https://shieldcn.dev/docs/cli) for full usage.\n\n## Usage\n\n```md\n![npm](https://shieldcn.dev/npm/react.svg)\n![stars](https://shieldcn.dev/github/stars/vercel/next.js.svg)\n![CI](https://shieldcn.dev/github/ci/jal-co/ui.svg)\n![license](https://shieldcn.dev/github/license/vercel/next.js.svg)\n![discord](https://shieldcn.dev/discord/1316199667142496307.svg)\n```\n\n### Badge groups\n\nCombine multiple badges into a single joined image — like a [shadcn ButtonGroup](https://ui.shadcn.com/docs/components/radix/button-group):\n\n\u003cp\u003e\n  \u003cimg src=\"https://shieldcn.dev/group/npm/react%2Bgithub/stars/vercel/next.js%2Bgithub/license/vercel/next.js.svg?variant=branded\" alt=\"badge group\" /\u003e\n\u003c/p\u003e\n\n```md\n![group](https://shieldcn.dev/group/npm/react+github/stars/vercel/next.js+github/license/vercel/next.js.svg?variant=branded)\n```\n\nJoin any badge paths with `+` under `/group/`. Query params apply to all segments. See the [Badge Group docs](https://shieldcn.dev/docs/badges/group).\n\n### Animated badges\n\n\u003cp\u003e\n  \u003cimg src=\"https://shieldcn.dev/badge/shieldcn-animated%20badges.gif?variant=branded\u0026size=lg\u0026logo=shieldcn\u0026logoColor=fff\u0026color=8b5cf6\u0026animate=shimmer\" alt=\"animated shieldcn badge\" /\u003e\n\u003c/p\u003e\n\nAdd `?animate=pulse`, `glow`, or `shimmer` to bring a badge to life:\n\n- **`pulse`** / **`glow`** animate the status dot (great for live, CI, or \"online\" badges)\n- **`shimmer`** sweeps a highlight across the whole badge\n\nFor `.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:\n\n```md\n\u003c!-- animates everywhere except GitHub READMEs (static frame there) --\u003e\n![status](https://shieldcn.dev/badge/status-online-22c55e.svg?statusDot=true\u0026animate=pulse)\n\n\u003c!-- animated GIF — animates inside GitHub READMEs too --\u003e\n![status](https://shieldcn.dev/badge/status-online-22c55e.gif?statusDot=true\u0026animate=pulse)\n```\n\nSee the [API reference](https://shieldcn.dev/docs/api-reference) for the full list of animation options.\n\n## Supported providers\n\nSee the [docs](https://shieldcn.dev/docs) for full endpoint details, interactive sandboxes, and copy-paste examples.\n\n### Package registries\n\n| Provider | Badges | Endpoint |\n|----------|--------|----------|\n| **npm** | version, downloads, license, node, types, dependents | `/npm/{package}` |\n| **PyPI** | version, downloads, license, python version | `/pypi/{package}` |\n| **Crates.io** | version, downloads, license | `/crates/{crate}` |\n| **Docker Hub** | pulls, stars, version, image size | `/docker/pulls/{image}` |\n| **Packagist** | version, downloads, license | `/packagist/v/{vendor}/{package}` |\n| **RubyGems** | version, downloads, license | `/rubygems/{gem}` |\n| **NuGet** | version, downloads | `/nuget/{package}` |\n| **Pub.dev** | version, likes, points, popularity | `/pub/{package}` |\n| **Homebrew** | version (formula + cask), installs, downloads | `/homebrew/{formula}` |\n| **Maven Central** | version | `/maven/{groupId}/{artifactId}` |\n| **CocoaPods** | version | `/cocoapods/{pod}` |\n| **JSR** | version, score | `/jsr/{@scope}/{name}` |\n| **Bundlephobia** | min size, minzip size, tree-shaking | `/bundlephobia/minzip/{package}` |\n| **Conda** | version, downloads, platform | `/conda/v/{channel}/{package}` |\n| **jsDelivr** | CDN hits, rank | `/jsdelivr/hits/npm/{package}` |\n| **Chocolatey** | version, downloads | `/chocolatey/v/{package}` |\n| **Snapcraft** | version | `/snapcraft/v/{snap}` |\n\n### Code platforms\n\n| Provider | Badges | Endpoint |\n|----------|--------|----------|\n| **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}` |\n| **GitLab** | stars, forks, issues, pipeline, license, release, contributors | `/gitlab/{owner}/{repo}/{topic}` |\n| **Codecov** | coverage percentage (color-coded) | `/codecov/{service}/{owner}/{repo}` |\n| **Coveralls** | coverage percentage (color-coded) | `/coveralls/{service}/{owner}/{repo}` |\n| **SonarCloud** | quality gate, bugs, vulnerabilities, coverage, maintainability, reliability, security | `/sonar/{topic}/{component}` |\n| **VS Code Marketplace** | installs, rating, version | `/vscode/installs/{publisher}/{extension}` |\n| **Open VSX** | version, downloads, rating | `/openvsx/v/{namespace}/{extension}` |\n\n### App stores\n\n| Provider | Badges | Endpoint |\n|----------|--------|----------|\n| **Chrome Web Store** | version, users, rating | `/chrome/v/{extensionId}` |\n| **Mozilla Add-ons** | version, users, rating, downloads | `/amo/v/{slug}` |\n| **Flathub** | version, downloads | `/flathub/v/{appId}` |\n| **F-Droid** | version | `/fdroid/v/{appId}` |\n\n### Social \u0026 Community\n\n| Provider | Badges | Endpoint |\n|----------|--------|----------|\n| **Discord** | online count, members | `/discord/{serverId}` |\n| **Reddit** | karma, subscribers | `/reddit/subscribers/r/{subreddit}` |\n| **Bluesky** | followers, following, posts | `/bluesky/{handle}` |\n| **X / Twitter** | follow CTA, mention CTA | `/x/follow/{username}` |\n| **YouTube** | subscribers, channel views, video views, likes, comments | `/youtube/subscribers/{channelId}` |\n| **Mastodon** | followers, following, posts | `/mastodon/followers/{instance}/{acct}` |\n| **Lemmy** | subscribers, posts, comments | `/lemmy/subscribers/{instance}/{community}` |\n| **Hacker News** | karma | `/hackernews/{userId}` |\n| **Twitch** | live status, followers | `/twitch/status/{login}` |\n| **Discourse** | topics, posts, users, likes | `/discourse/topics/{server}` |\n| **Matrix** | room members | `/matrix/members/{roomAlias}` |\n| **Stack Exchange** | tag questions, user reputation | `/stackexchange/tag/{tag}` |\n\n### Funding \u0026 Tools\n\n| Provider | Badges | Endpoint |\n|----------|--------|----------|\n| **Open Collective** | backers, sponsors, contributors, balance, budget | `/opencollective/backers/{slug}` |\n| **Liberapay** | receiving, patrons, goal | `/liberapay/receiving/{username}` |\n| **WakaTime** | coding time | `/wakatime/{username}` |\n| **Weblate** | translation %, language count | `/weblate/translation/{server}/{project}/{component}` |\n| **Modrinth** | downloads, followers, version, game versions | `/modrinth/downloads/{slug}` |\n| **Tokscale** | tokens, cost, rank, active days | `/tokscale/{username}` |\n\n### Custom badges\n\n| Type | Description | Endpoint |\n|------|-------------|----------|\n| **Badge Group** | Multiple badges joined in one image | `/group/{badge1}+{badge2}+{badge3}` |\n| **Static** | Custom label/message/color | `/badge/{label}-{message}-{color}` |\n| **Dynamic JSON** | Fetch any JSON API | `/badge/dynamic/json?url=...\u0026query=...` |\n| **HTTPS Endpoint** | Proxy any JSON endpoint | `/https/{hostname}/{path}` |\n| **Memo** | User-stored badges (PUT API) | `/memo/{key}` |\n\n## Variants \u0026 sizes\n\nEvery badge supports shadcn Button variants and sizes:\n\n```md\n![default](https://shieldcn.dev/npm/react.svg)\n![secondary](https://shieldcn.dev/npm/react.svg?variant=secondary)\n![outline](https://shieldcn.dev/npm/react.svg?variant=outline)\n![ghost](https://shieldcn.dev/npm/react.svg?variant=ghost)\n![destructive](https://shieldcn.dev/npm/react.svg?variant=destructive)\n![branded](https://shieldcn.dev/npm/react.svg?variant=branded)\n\n![xs](https://shieldcn.dev/npm/react.svg?size=xs)\n![sm](https://shieldcn.dev/npm/react.svg?size=sm)\n![default](https://shieldcn.dev/npm/react.svg?size=default)\n![lg](https://shieldcn.dev/npm/react.svg?size=lg)\n```\n\n## Icons\n\nThree icon libraries (40,000+ icons) plus custom SVG upload:\n\n- **[Simple Icons](https://simpleicons.org)** — `?logo=react`\n- **[React Icons](https://react-icons.github.io/react-icons/)** — `?logo=ri:GoStarFill`\n- **[React Icons](https://react-icons.github.io/react-icons/)** — `?logo=ri:FaReact`\n- **Custom SVG** — `?logo=data:image/svg+xml;base64,...` — upload any SVG icon via the Badge Builder or encode it yourself\n\n## Response formats\n\n- **`.png`** — PNG image (recommended for GitHub READMEs and maximum compatibility)\n- **`.svg`** — SVG image (scalable, smaller file size)\n- **`.json`** — raw badge data\n- **`/shields.json`** — shields.io-compatible endpoint\n\nBoth `.png` and `.svg` work everywhere GitHub renders images. Just swap the extension.\n\n## Design principles\n\n- **shadcn buttons, not shields.io rectangles** — badges are rendered as actual shadcn Button components with real Inter font outlines via Satori\n- **Everything configurable** — variant, size, mode, colors, icons, opacity, split, dot — but sensible defaults so you don't have to configure anything\n- **Shields.io compatible** — same URL patterns for static/dynamic badges, same text encoding, shields.io JSON endpoint support\n- **Open source, never paywalled** — every badge type, every variant, every icon source is free\n\n## Agent skill\n\nInstall 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:\n\n```bash\nnpx skills add jal-co/shieldcn\n```\n\nOnce installed, ask your agent to _\"add shieldcn badges to the README\"_ — it knows all providers, URL patterns, and query parameters.\n\nLearn more in the [skill docs](https://shieldcn.dev/docs/skill).\n\n## Self-Hosting\n\nRun your own badge engine with Docker:\n\n```bash\ngit clone https://github.com/jal-co/shieldcn.git\ncd shieldcn\ndocker compose -f packages/engine/docker-compose.yml up -d\n\n# Test it\ncurl http://localhost:3000/badge/self--hosted-green.svg\n```\n\nOr pull the pre-built image:\n\n```bash\ndocker pull ghcr.io/jal-co/shieldcn/engine:latest\n```\n\nSee the [Self-Hosting Guide](https://shieldcn.dev/docs/self-hosting) for full setup details.\n\n## Local Development\n\n```bash\npnpm install             # install all workspace deps\npnpm dev:web             # start the web site\npnpm dev:engine          # start the self-hosted engine\npnpm build:web           # build the web site\npnpm build:engine        # build the engine\n```\n\nThe repo is a Turborepo monorepo with three packages:\n- `packages/core` — shared badge engine library\n- `packages/web` — marketing site (Vercel)\n- `packages/engine` — self-hosted Docker image\n\n\n## Token pool\n\nshieldcn 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.\n\n## Credits\n\n- **[shields.io](https://shields.io)** — the original badge service. Inspiration for URL patterns, static badge format, and the token pool system.\n- **[badgen.net](https://badgen.net)** — inspiration for many badge types and endpoint structures, especially the GitHub badge coverage.\n- **[shadcn/ui](https://ui.shadcn.com)** — the design system these badges are built on.\n- **[Satori](https://github.com/vercel/satori)** — Vercel's JSX-to-SVG engine that makes rendering React components as badge images possible.\n- **[jal-co/ui](https://ui.justinlevine.me)** — the component library powering the docs site.\n- **[@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.\n\n## Contributing\n\nPRs welcome. See [AGENTS.md](./AGENTS.md) for architecture overview.\n\nTo add shadcn components: `cd packages/web \u0026\u0026 pnpm dlx shadcn@latest add {component}`\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjal-co%2Fshieldcn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjal-co%2Fshieldcn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjal-co%2Fshieldcn/lists"}