lighthouse-badges

A CLI tool to generate Lighthouse score badges, JSON, or SVG using local Chrome and the Lighthouse npm package.

Installation

bun add -g @hidao/lighthouse-badges

Or with npm:

npm install -g @hidao/lighthouse-badges

Requirements

• Node.js >= 22.19
• Google Chrome installed on your system

Usage

bunx github:hidao80/lighthouse-badges <URL> [options]

Or with npx:

npx github:hidao80/lighthouse-badges <URL> [options]

Options

| Option | Description | |--------|-------------| | (none) | Output Markdown badges | | -b, --badge | Output Markdown badges | | -j, --json | Output JSON | | -s, --svg | Output SVG with donut charts |

Examples

Markdown Badges (default)

bunx github:hidao80/lighthouse-badges https://example.com

Output:

![Accessibility](https://img.shields.io/badge/Accessibility-94-brightgreen?style=flat-square) ![Best_Practices](https://img.shields.io/badge/Best_Practices-100-brightgreen?style=flat-square) ![Performance](https://img.shields.io/badge/Performance-93-brightgreen?style=flat-square) ![SEO](https://img.shields.io/badge/SEO-72-yellow?style=flat-square)

Rendered:

JSON Output

bunx github:hidao80/lighthouse-badges https://example.com -j

Output:

{
  "performance": 100,
  "accessibility": 100,
  "bestPractices": 93,
  "seo": 72
}

SVG Output

bunx github:hidao80/lighthouse-badges https://example.com -s

Outputs an SVG string with donut charts for each score.

Output:

<svg width="480" height="120" viewBox="0 0 480 120" xmlns="http://www.w3.org/2000/svg">

    <g transform="translate(0, 0)">
      <circle cx="60" cy="60" r="16" fill="none" stroke="#e0e0e0" stroke-width="8" transform="rotate(-90 60 60)" />
      <circle cx="60" cy="60" r="16" fill="none" stroke="#0cce6b" stroke-width="8"
        stroke-dasharray="100.53096491487338" stroke-dashoffset="6.031857894892408"
        stroke-linecap="round" transform="rotate(-90 60 60)" />
      <text x="60" y="70" text-anchor="middle" font-size="22" font-family="Arial" fill="#0cce6b">
        94
      </text>
    </g>


    <g transform="translate(120, 0)">
      <circle cx="60" cy="60" r="16" fill="none" stroke="#e0e0e0" stroke-width="8" transform="rotate(-90 60 60)" />
      <circle cx="60" cy="60" r="16" fill="none" stroke="#0cce6b" stroke-width="8"
        stroke-dasharray="100.53096491487338" stroke-dashoffset="0"
        stroke-linecap="round" transform="rotate(-90 60 60)" />
      <text x="60" y="70" text-anchor="middle" font-size="22" font-family="Arial" fill="#0cce6b">
        100
      </text>
    </g>


    <g transform="translate(240, 0)">
      <circle cx="60" cy="60" r="16" fill="none" stroke="#e0e0e0" stroke-width="8" transform="rotate(-90 60 60)" />
      <circle cx="60" cy="60" r="16" fill="none" stroke="#0cce6b" stroke-width="8"
        stroke-dasharray="100.53096491487338" stroke-dashoffset="10.053096491487336"
        stroke-linecap="round" transform="rotate(-90 60 60)" />
      <text x="60" y="70" text-anchor="middle" font-size="22" font-family="Arial" fill="#0cce6b">
        90
      </text>
    </g>


    <g transform="translate(360, 0)">
      <circle cx="60" cy="60" r="16" fill="none" stroke="#e0e0e0" stroke-width="8" transform="rotate(-90 60 60)" />
      <circle cx="60" cy="60" r="16" fill="none" stroke="#0cce6b" stroke-width="8"
        stroke-dasharray="100.53096491487338" stroke-dashoffset="10.053096491487336"
        stroke-linecap="round" transform="rotate(-90 60 60)" />
      <text x="60" y="70" text-anchor="middle" font-size="22" font-family="Arial" fill="#0cce6b">
        72
      </text>
    </g>

</svg>

Rendered:

Badge Colors

| Score | Color | |-------|-------| | 90-100 | Green | | 50-89 | Yellow | | 0-49 | Red |

Quick Start

Run with Docker

# Production build
docker build -t lighthouse-badges .
docker run lighthouse-badges https://example.com

Run directly

bunx github:hidao80/lighthouse-badges https://example.com

Or with npx:

npx github:hidao80/lighthouse-badges https://example.com

Development

bun install
bun run build   # tsc -> bin/
bun run dev     # tsc --watch
bun run lint    # biome check src/ tests/

bin/ is the compiled CLI and is committed to git, so npx/bunx github:... runs it directly with no install-time build step. After changing src/, run bun run build and commit the resulting bin/ diff. See AGENTS.md for the full contributor guide and docs/ADR.md for the reasoning behind these choices.

License

MIT