Beautiful README badges. A shields.io alternative styled as shadcn/ui buttons. Never paywalled.

Shieldcn offers a free, open-source alternative to shields.io, providing beautifully styled README badges inspired by shadcn/ui. It targets developers seeking to enhance project documentation with modern, customizable badges rendered as SVGs. The service is entirely free, with no paywalls or hidden costs, and supports extensive customization options.

How It Works

Badges are rendered as actual shadcn/ui Button components using Vercel's Satori engine, ensuring pixel-perfect replication of styles like fonts (Inter), border-radius, padding, and color tokens. This approach generates scalable SVG images directly from React components, offering a distinct visual appeal compared to traditional badge services. The project is built using jal-co/ui components and a shared badge engine library within a Turborepo monorepo structure.

Quick Start & Requirements

• CLI: Install via npx shieldcn-cli for local badge generation, README injection, and shields.io migration.
• Self-Hosting: Clone the repository, navigate to the shieldcn directory, and run docker compose -f packages/engine/docker-compose.yml up -d. A pre-built Docker image is available (ghcr.io/jal-co/shieldcn/engine:latest).
• Local Development: Requires pnpm for dependency management (pnpm install, pnpm dev:engine).
• Links: Homepage, Docs, CLI, API Reference are mentioned but not provided as direct URLs.

Highlighted Details

• Broad Provider Support: Integrates with numerous package registries, code platforms (GitHub, GitLab, Codecov), app stores, social networks, and funding tools.
• Badge Groups: Allows combining multiple badges into a single image, similar to a shadcn/ui ButtonGroup.
• shadcn/ui Styling: Badges are rendered as actual shadcn/ui Button components, ensuring consistent design.
• Customization: Supports shadcn/ui variants, sizes, modes, colors, and integrates multiple icon libraries (Simple Icons, React Icons) plus custom SVG uploads.
• Response Formats: Offers .png (recommended), .svg, and .json (shields.io compatible) outputs.
• AI Integration: Features an installable skill (npx skills add jal-co/shieldcn) for AI coding agents to automate badge integration.

Maintenance & Community

Created by Justin Levine, the project relies on a community token pool (inspired by shields.io) to distribute GitHub API requests. Users can contribute by authorizing a read-only OAuth app. The project maintains an X (Twitter) presence.

Licensing & Compatibility

Licensed under MIT, permitting commercial use and integration into closed-source projects without significant restrictions.

Limitations & Caveats

The service utilizes a token pool for GitHub API requests, which may introduce rate limiting considerations. As a newer alternative to shields.io, its long-term adoption and maintenance trajectory are still developing.