Badge Badger 🦡

A CLI tool that automatically updates tech badges in your README.md based on your package.json dependencies.

"Oh your badges are out of date? Badge Badger don't care. It fixed them."

You'll end up with those familiar badges in your readme, just like these badges for this repo, but always kept up-to-date as your tech stack evolves and updates over time.

📦 Installation

⚡ Using npx (Recommended - No installation required)

You can run Badge Badger directly without any installation:

npx badge-badger

Benefits:

• ✅ Always gets the latest version from npm
• ✅ No global installation needed
• ✅ Perfect for occasional use
• ✅ No need to manage updates

🌍 Global Installation

For frequent users who want faster execution:

npm install -g badge-badger

Then, you can run the badger command in any project directory:

badger

Benefits:

• ✅ Faster execution (already installed)
• ✅ Works offline
• ✅ Good for developers who use it frequently

Note: When you have a global installation, Badge Badger will automatically check for updates and notify you when a newer version is available.

🏠 Local Installation

npm install --save-dev badge-badger

Then, you can run the command using npx:

npx badger

🚀 Usage

The tool provides comprehensive badge management through an interactive CLI:

1. 📖 Reads your package.json to get dependency versions
2. 🔍 Automatically detects all your technologies using our smart badge library
3. 🎛️ Interactive selection lets you choose which badges to add, keep, update, or remove
4. 📊 Comprehensive reporting shows exactly what changed (additions, updates, removals)
5. 📍 Smart placement using marker comments for precise control

Interactive Badge Management

When you run badger, you'll see an interactive prompt showing:

• Current badges already in your README (pre-selected to keep)
• New badges available from your dependencies (optional to add)
• Version indicators showing which badges can be updated (🔄) vs up to date (✅)
• Selection interface to choose which badges to display

badger
# Interactive: Choose which badges to keep/add/remove
# Output: "✨ 2 new badges added and 🦡 1 badge updated to your README."

Badge Operations

Adding Badges: Select new badges from your dependencies

# Output: "✨ 3 new badges added to your README."

Updating Badges: Existing badges automatically update when versions change

# Output: "🦡 2 badges updated to your README."

Removing Badges: Deselect badges you want to remove

# Output: "🗑️ 1 badge removed from your README."

Combined Operations: Multiple actions in one session

# Output: "🗑️ 1 badge removed, ✨ 1 new badge added, and 🦡 1 badge updated to your README."

Managing Unrecognized Badges

Badge Badger can detect and help you manage "unrecognized" badges - badges in your README that don't correspond to any dependencies in your package.json. This is useful for:

• Custom badges for tools or services you're using
• Manual badges you added for technologies without npm packages
• Cleanup of badges for dependencies you've removed

When unrecognized badges are detected, they appear in the interactive prompt with a 🔍 icon:

badger
# Interactive: Choose which unrecognized badges to keep or remove
# Output: "🗑️ 2 unrecognized badges removed from your README."

Features:

• 🔍 Visual indicators - Unrecognized badges are clearly marked
• ✅ Safe defaults - Unrecognized badges are preserved by default
• 🎯 Selective removal - Choose which ones to keep or remove
• 🛡️ Non-interactive safety - Unrecognized badges are preserved in automated runs

Smart Defaults

• ✅ Existing badges are kept - Your current setup is preserved
• ⚪ New badges are optional - You choose whether to add them
• 🛡️ Safe removal - You must explicitly deselect badges to remove them
• 🚀 Quick acceptance - Press Enter to keep current setup
• 🔄 Version indicators - See which badges can be updated vs up to date

Alternatively, you can use the Automated Workflow Installation in your repo for an automated approach.

🎯 Smart Badge Library

Badge Badger includes a comprehensive smart badge library with over 200+ popular packages and technologies. The library automatically detects your project's dependencies and adds relevant badges with proper branding colors - no configuration needed!

📋 View Complete Badge Catalog →

Want to see all possible badges and examples? Check out badge_catalog.md for a full visual reference!

⚙️ Advanced Configuration (Optional)

While the tool works automatically without any configuration, you can optionally customize which badges to track by creating a badger.config.js file in your project root:

export default [
  {
    name: 'Custom Tool',
    npm: 'custom-tool',
    link: 'https://custom-tool.dev',
    logo: 'customtool',
    color: '61DAFB',
  },
];

🔧 Badge Configuration Options

Each badge object supports the following properties:

• name: The display name for the badge
• npm: The npm package name to check in package.json
• link: The URL the badge should link to
• logo: The logo name for shields.io (optional)
• color: The hex color for the badge (without #)

🔄 How It Works

1. 📖 Reads package.json: Extracts dependencies and devDependencies.
2. 🧠 Smart Badge Detection: Uses the curated badge library to find relevant badges.
3. 🔍 Existing Badge Detection: Scans your README for current badges and their versions.
4. 🎯 Interactive Selection: Presents you with detected technologies to choose from:
   • Current badges are pre-selected (preserved by default)
   • New badges are optional (you choose to add them)
   • Version updates are detected automatically
5. 📊 Comprehensive Reporting: Shows exactly what changed:
   • ✨ Additions: New badges added to your README
   • 🦡 Updates: Existing badges updated with new versions
   • 🗑️ Removals: Badges removed from your README
6. 📍 Smart Badge Placement:
   • Looks for special begin and end marker comments in your README
   • If found, replaces all content between the markers with selected badges
   • If not found, adds the markers and badges after your main title
7. ✅ Badge Verification: Checks if badges exist on shields.io and provides fallbacks.

Note: For detailed information about badge placement control, interactive selection, and comprehensive badge management, see Interactive Badge Selection & Comprehensive Badge Management.

🔄 Automated Workflow Installation

For continuous badge updates, you can install a GitHub Actions workflow:

badger workflow

This will create a workflow that automatically updates badges when your package.json changes.

🔧 Workflow Installation Options

When installing the workflow, you'll be prompted with options if a workflow already exists:

• Overwrite with latest version - Replace existing workflow
• Backup existing and install latest - Create backup before overwriting
• Skip installation - Keep existing workflow

📚 Additional Documentation

• 📋 Badge Catalog - Complete visual reference of all available badges
• 🖱️ Interactive Selection - Detailed guide to interactive badge selection and comprehensive badge management
• 📊 Comprehensive Reporting - Complete guide to the reporting system and message types
• 🤝 Contributing - How to contribute to Badge Badger
• 🔧 Development - Development setup and workflows
• 🚀 Release Guide - Complete guide for publishing releases to npm

📦 Contributing & Releases

This project uses Changesets for version management and automated releases.

🔍 For Contributors

When making changes that should be included in a release:

1. Create a changeset file in the .changeset directory:

   mkdir -p .changeset
   echo '---
   "badge-badger": patch
   ---
   
   Brief description of your changes' > .changeset/$(date +%s).md

2. Submit your PR - The workflow will automatically check for changesets

3. Merge to main - This triggers automated versioning and releases

🚀 For Maintainers

Releases are fully automated via GitHub Actions:

1. Changesets are created during development
2. Merge to main triggers the release workflow
3. Version PR is created automatically
4. Review and merge the version PR
5. Package is published to npm automatically

📖 See the complete Release Guide → for detailed setup instructions, troubleshooting, and testing procedures.

Changeset Types

• patch: Bug fixes and minor changes
• minor: New features (backward compatible)
• major: Breaking changes

See .changeset/README.md for detailed examples and instructions.

📄 License

MIT

This README was last updated by Badge Badger. Don't worry, it's friendly!

🖱️ Interactive Badge Selection

Badge Badger uses interactive badge selection by default! This means you can choose exactly which badges to display in your README, and your choices are automatically saved in the README itself.

🎯 Default Behavior (Interactive)

badger

You'll be presented with a list of detected technologies and can select which badges to include. Existing badges in your README are kept by default.

🔧 Command Options

• Preview changes without writing:

  badger --dry-run

• Reset all badges (start fresh):

  badger --reset

🧠 Smart Defaults

• ✅ Existing badges in your README are pre-selected and kept
• ⚪ New badges are not selected by default (you can add them if you want)
• 🚀 Quick setup - Just press Enter to keep your current badges only

📋 Example Interactive Session

$ badger

🦡 Badge Badger - Interactive Selection

📋 Current badges in README:
✅ React (react)
✅ TypeScript (typescript)

🆕 New badges available:
⚪ Vite (vite)
⚪ ESLint (eslint)

💾 2/2 current badges will be kept

◆  Select badges to display in your README (Enter, to accept without changes):
[x] React (react)          # Pre-selected (already in README)
[x] TypeScript (typescript) # Pre-selected (already in README)
[ ] Vite (vite)            # Can select to add
[ ] ESLint (eslint)        # Can select to add

# Just press Enter to keep current badges only!

💾 No Configuration Files

Your badge selections are stored directly in your README using the marker system, so there's no need for additional configuration files. The marker comment serves as both the insertion point and the record of your badge choices.