https://github.com/santana-org/starmie
📊 Dynamic SVG widgets for open-source communities
https://github.com/santana-org/starmie
actions community santana-org svg
Last synced: 24 days ago
JSON representation
📊 Dynamic SVG widgets for open-source communities
- Host: GitHub
- URL: https://github.com/santana-org/starmie
- Owner: santana-org
- Created: 2026-05-30T04:43:32.000Z (24 days ago)
- Default Branch: main
- Last Pushed: 2026-05-30T04:59:28.000Z (24 days ago)
- Last Synced: 2026-05-30T06:22:15.785Z (24 days ago)
- Topics: actions, community, santana-org, svg
- Language: TypeScript
- Homepage:
- Size: 65.4 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
starmie
Generate beautiful SVG community widgets for GitHub READMEs — as a CLI tool or GitHub Action.
[](./LICENSE)
[](https://pnpm.io)
[](https://www.npmjs.com/package/starmie)
[](https://github.com/santana-org/starmie/actions/workflows/ci.yml)
---
## 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.
```yaml
# .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`](./.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`](#️-configuration).
### Embed the SVGs
After the first run, reference the generated files in your README:
```markdown
## 👥 Contributors
## 🏆 Top Contributors
## 💖 Sponsors
## 📊 Stats
```
---
## 🖥️ CLI
Install globally and run it from your project root:
```sh
pnpm add -g starmie
# or: npm install -g starmie
```
```sh
# 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 ` | GitHub repository | `$GITHUB_REPOSITORY` |
| `--theme ` | Visual theme: `white`, `dark` | `white` |
| `--output ` | Output directory | `community` |
| `--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.
```yaml
# .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
```sh
# 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`](./.github/workflows/ci.yml) workflow: type check + build.
### Releasing
Push a version tag to trigger the [`release.yml`](./.github/workflows/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
```sh
git tag v1.2.0
git push origin v1.2.0
```
---
## 🏗️ Built with
[TypeScript](https://www.typescriptlang.org) · [pnpm](https://pnpm.io) · [@santana-org/cli](https://www.npmjs.com/package/@santana-org/cli) · [@santana-org/logger](https://www.npmjs.com/package/@santana-org/logger) · [js-yaml](https://github.com/nodeca/js-yaml)