starmie

What it does

Starmie fetches live data from the GitHub API and renders it as self-contained SVG files you can embed directly in any Markdown file. No external services, no JavaScript — just static SVGs committed to your repo and served by GitHub's CDN.

Four widgets out of the box:

| Widget | Output file | What it shows | |---|---|---| | Contributors Wall | community/contributors.svg | Avatar grid of every contributor | | Top Contributors | community/top-contributors.svg | Ranked list with commit counts | | Sponsors Wall | community/sponsors.svg | Avatar grid of GitHub Sponsors | | Repo Stats | community/stats.svg | Stars, forks, issues, PRs |

👁️ Live examples

These SVGs are generated by Starmie itself, running on this repo.

Contributors

Top Contributors

Sponsors

Stats

🚀 GitHub Action (recommended)

Add a workflow and forget about it. Starmie runs on every push to main, regenerates the SVGs, and commits them back to your repo automatically.

# .github/workflows/readme-wall.yml
name: Update community widgets

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * 0'   # also refresh every Sunday
  workflow_dispatch:

permissions:
  contents: write

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: santana-org/starmie@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          theme: dark            # white | dark  (default: white)
          output-dir: community  # where SVGs are written (default: community)

This repo uses uses: ./ instead of santana-org/starmie@v1 to always run from the local source — see .github/workflows/readme-wall.yml.

Action inputs

| Input | Required | Default | Description | |---|---|---|---| | token | yes | ${{ github.token }} | GitHub token with repo read access | | repo | no | current repo | Target repository (owner/repo) | | theme | no | white | Visual theme: white or dark | | output-dir | no | community | Directory where SVGs are written |

Widget selection and fine-grained options are controlled by .readme-wall.yml.

Embed the SVGs

After the first run, reference the generated files in your README:

## 👥 Contributors
![Contributors](./community/contributors.svg)

## 🏆 Top Contributors
![Top Contributors](./community/top-contributors.svg)

## 💖 Sponsors
![Sponsors](./community/sponsors.svg)

## 📊 Stats
![Stats](./community/stats.svg)

🖥️ CLI

Install globally and run it from your project root:

pnpm add -g starmie
# or: npm install -g starmie

# Generate all enabled widgets (reads .readme-wall.yml if present)
starmie generate --repo owner/repo --theme dark

# Individual widgets
starmie contributors --repo owner/repo
starmie top          --repo owner/repo
starmie sponsors     --repo owner/repo
starmie stats        --repo owner/repo

Global options

| Flag | Description | Default | |---|---|---| | --repo <owner/repo> | GitHub repository | $GITHUB_REPOSITORY | | --theme <name> | Visual theme: white, dark | white | | --output <dir> | Output directory | community | | --token <token> | GitHub token | $GITHUB_TOKEN |

A GITHUB_TOKEN environment variable is required for API access (unauthenticated requests are rate-limited to 60/hour).

⚙️ Configuration

Create .readme-wall.yml in your project root to control which widgets are generated and how they look. All fields are optional — the file itself is optional.

# .readme-wall.yml
theme: dark          # white | dark

output: community    # output directory

contributors:
  enabled: true
  max: 24            # maximum avatars to show
  showCount: true    # show total contributor count in header

topContributors:
  enabled: true
  max: 10            # number of contributors to rank

sponsors:
  enabled: true

stats:
  enabled: true

Defaults

| Key | Default | |---|---| | theme | white | | output | community | | contributors.enabled | true | | contributors.max | 24 | | contributors.showCount | true | | topContributors.enabled | true | | topContributors.max | 10 | | sponsors.enabled | true | | stats.enabled | true |

🎨 Themes

| Theme | Description | |---|---| | white | Light background, clean lines, neutral palette | | dark | Dark surface, high-contrast text, suited for dark-mode READMEs |

🛠️ Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run CLI locally (no build needed)
pnpm dev generate --repo owner/repo

# Run the GitHub Action entrypoint locally
pnpm action:dev

# Type check
pnpm typecheck

CI

Every push to main and every pull request runs the ci.yml workflow: type check + build.

Releasing

Push a version tag to trigger the release.yml workflow, which:

1. Builds the project
2. Publishes the package to npm (NPM_TOKEN secret required)
3. Creates a GitHub Release with a generated changelog and a tarball of the build artifacts

git tag v1.2.0
git push origin v1.2.0

🏗️ Built with

TypeScript · pnpm · @santana-org/cli · @santana-org/logger · js-yaml