Badge Maker

Badge Maker is a comprehensive SVG badge generation library that enables developers to create customizable badges for various use cases including CI/CD status indicators, version displays, and project metrics. It offers both programmatic API and CLI interfaces for generating SVG badges with configurable labels, messages, colors, styles, and logos, supporting multiple visual themes and color specification methods.

Package Information

• Package Name: badge-maker
• Package Type: npm
• Language: JavaScript/TypeScript
• Installation: npm install badge-maker

Core Imports

import { makeBadge, ValidationError } from "badge-maker";

For CommonJS:

const { makeBadge, ValidationError } = require("badge-maker");

Basic Usage

import { makeBadge, ValidationError } from "badge-maker";

// Simple badge
const format = {
  label: "build",
  message: "passing",
  color: "brightgreen"
};

const svg = makeBadge(format);
console.log(svg); // SVG string

// Advanced badge with logo and links
const advancedFormat = {
  label: "npm",
  message: "v5.0.2",
  color: "#cb3837",
  style: "for-the-badge",
  logoBase64: "data:image/svg+xml;base64,...",
  links: ["https://npmjs.com/package/badge-maker", "https://github.com/badges/shields"]
};

const advancedSvg = makeBadge(advancedFormat);

// Error handling
try {
  makeBadge({}); // Missing required message field
} catch (error) {
  if (error instanceof ValidationError) {
    console.error("Validation failed:", error.message);
  }
}

Capabilities

Badge Generation

Generate SVG badges with configurable appearance and content.

function makeBadge(format: Format): string;

The makeBadge function creates an SVG badge based on the provided format configuration. It validates all input parameters and returns a complete SVG string ready for use in web pages, documentation, or other applications.

Parameters:

• format (Format): Badge configuration object containing label, message, colors, style, and optional logo/links

Returns: SVG string representing the generated badge

Throws: ValidationError when format validation fails

Error Handling

Custom error class for validation failures.

class ValidationError extends Error {
  constructor(message: string);
}

The ValidationError class is thrown when invalid parameters are passed to makeBadge. Common validation errors include missing required fields, invalid field types, or unsupported values.

Types

Format Interface

interface Format {
  label?: string;
  message: string;
  labelColor?: string;
  color?: string;
  style?: 'plastic' | 'flat' | 'flat-square' | 'for-the-badge' | 'social';
  logoBase64?: string;
  links?: Array<string>;
  idSuffix?: string;
}

Properties:

• label (optional): Text displayed on the left side of the badge (e.g., "build", "npm", "version"). If empty string provided, badge displays only the message section.
• message (required): Text displayed on the right side of the badge (e.g., "passing", "v1.0.0", "stable")
• labelColor (optional): Background color for the label section
• color (optional): Background color for the message section
• style (optional): Visual appearance of the badge, defaults to "flat"
• logoBase64 (optional): Base64-encoded logo data (data URI format) to display on the left. Logo appears with default height of 14px.
• links (optional): Array of up to 2 URLs for making badge sections clickable. First URL applies to label section, second to message section.
• idSuffix (optional): Unique identifier suffix for multiple badges on the same page to prevent CSS conflicts when badges are embedded inline in HTML

Color Support

Badge Maker supports multiple color specification methods:

Named Colors

Built-in color names for common use cases:

• brightgreen (#4c1) - Success states
• green (#97ca00) - Passing tests
• yellow (#dfb317) - Warnings
• yellowgreen (#a4a61d) - Moderate success
• orange (#fe7d37) - Cautions
• red (#e05d44) - Failures
• blue (#007ec6) - Information
• grey (#555) - Neutral states
• lightgrey (#9f9f9f) - Inactive states

Color Aliases

Semantic color names that map to the named colors above:

• gray → grey
• lightgray → lightgrey
• critical → red
• important → orange
• success → brightgreen
• informational → blue
• inactive → lightgrey

Custom Colors

• Hex colors: #rgb or #rrggbb format (e.g., #4c1, #cb3837)
• CSS colors: Any valid CSS color value (e.g., steelblue, rgb(255, 0, 0))

Badge Styles

Badge Maker supports five distinct visual styles:

flat (default)

Clean, modern flat design with subtle gradients.

plastic

3D appearance with pronounced gradients and highlights.

flat-square

Minimalist flat design with sharp, square corners.

for-the-badge

Large, bold style popular in GitHub README files.

social

Social media style with drop shadows and rounded appearance.

CLI Usage

Badge Maker includes a command-line interface for quick badge generation through the badge command:

npm install -g badge-maker

# Basic usage with named color (colon prefix)
badge build passing :brightgreen > badge.svg

# Using custom hex colors
badge npm v5.0.2 "#cb3837" > npm-badge.svg

# With label color and message color
badge tests 95% brightgreen lightgrey > coverage.svg

# Adding style with @ prefix
badge cactus grown :green @flat > example.svg

CLI Syntax:

badge label message [:color] [@style]
badge label message color [labelColor] [@style]

• label: Badge label text
• message: Badge message text (required)
• :color: Named color with colon prefix (e.g., :brightgreen, :red)
• color: Custom color without colon (hex, CSS color names, etc.)
• labelColor: Optional label background color (when using custom colors)
• @style: Style with @ prefix (e.g., @plastic, @social, @for-the-badge)

Examples:

• badge cactus grown :green @flat - Named color with style
• badge build failed red - Custom color
• badge test 95% green lightgrey @flat-square - Both colors with style

Usage Examples

Build Status Badges

// Passing build
const passingBuild = makeBadge({
  label: "build",
  message: "passing",
  color: "brightgreen"
});

// Failed build
const failedBuild = makeBadge({
  label: "build", 
  message: "failed",
  color: "red"
});

Version Badges

// NPM version with logo
const npmVersion = makeBadge({
  label: "npm",
  message: "v5.0.2",
  color: "#cb3837",
  style: "flat-square",
  logoBase64: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI0MCIgaGVpZ2h0PSI0MCI+PHBhdGggZD0iTTAgMGg0MHY0MEgweiIgZmlsbD0iI2NiMzgzNyIvPjwvc3ZnPg=="
});

Custom Styled Badges

// Social style with links
const socialBadge = makeBadge({
  label: "follow",
  message: "@shields_io",
  color: "blue",
  style: "social",
  links: ["https://twitter.com/shields_io"]
});

// For-the-badge style
const largeBadge = makeBadge({
  label: "MADE WITH",
  message: "JAVASCRIPT",
  color: "yellow",
  labelColor: "black", 
  style: "for-the-badge"
});

Multiple Badges with ID Suffixes

// When displaying multiple badges on the same page
const badge1 = makeBadge({
  label: "test",
  message: "passing",
  color: "green",
  idSuffix: "1"
});

const badge2 = makeBadge({
  label: "coverage",
  message: "95%",
  color: "brightgreen",
  idSuffix: "2"
});

Error Handling

Badge Maker performs comprehensive validation and provides detailed error messages:

import { makeBadge, ValidationError } from "badge-maker";

try {
  makeBadge({
    // Missing required 'message' field
    label: "test"
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(error.message); // "Field `message` is required"
  }
}

// Common validation errors:
// - "makeBadge takes an argument of type object"
// - "Field `message` is required"  
// - "Field `labelColor` must be of type string"
// - "Field `color` must be of type string"
// - "Field `message` must be of type string"
// - "Field `label` must be of type string"
// - "Field `logoBase64` must be of type string"
// - "Field `links` must be an array of strings"
// - "Field `links` must not have more than 2 elements"
// - "Field `style` must be one of (plastic,flat,flat-square,for-the-badge,social)"
// - "Field `idSuffix` must contain only numbers, letters, -, and _"
// - "Unexpected field 'invalidField'. Allowed values are (label,message,labelColor,color,style,logoBase64,links,idSuffix)"