GitWidgets

Dynamic SVG widgets for GitHub READMEs — stats, streak, top languages, and more.
One engine. Three delivery channels. Zero lock-in.

---

Widgets

Widget	Endpoint	Status
Stats card	GET /api/stats.svg	✅ Live
Streak	GET /api/streak.svg	✅ Live
Summary (top languages)	GET /api/summary.svg	✅ Live
Activity Graph	—	⏳ Post-MVP

Quick embed

![GitHub Stats](https://gitwidgets.dev/api/stats.svg?username=yourname)
![GitHub Streak](https://gitwidgets.dev/api/streak.svg?username=yourname)
![Top Languages](https://gitwidgets.dev/api/summary.svg?username=yourname)

Common parameters

Param	Default	Description
username	required	GitHub username
theme	dark	See Themes
tz	UTC	IANA timezone (e.g. America/Sao_Paulo) — affects streak "today"

Full parameter reference: gitwidgets.dev/docs

---

Themes

10 themes, zero config — swap with a single param.

Theme	ID
Dark	dark
Light	light
Glass	glass
Minimal	minimal
Terminal	terminal
Brutalist	brutalist
Synthwave	synthwave
Bauhaus	bauhaus
Bloomberg	bloomberg
Sticker	sticker

---

Delivery channels

1. Public API (zero setup)

Paste a URL directly in your README:

![stats](https://gitwidgets.dev/api/stats.svg?username=yourname&theme=glass)

2. GitHub Action (self-hosted, no runtime dependency)

- uses: gitwidgets-org/gitwidgets@v1
  with:
    username: ${{ github.repository_owner }}
    github_token: ${{ secrets.GITHUB_TOKEN }}

Generates static SVGs committed back to your repo — no dependency on our infra at runtime.

3. Web Dashboard

Visit gitwidgets.dev to build URLs visually, preview widgets live, compare two GitHub profiles side by side, and copy embed code in Markdown, HTML, or React.

4. JavaScript / TypeScript SDK

npm install @gitwidgets/sdk

import { Stats, Streak } from '@gitwidgets/sdk/react'

export default function Profile() {
  return (
    <>
      <Stats username="torvalds" theme="dark" />
      <Streak username="torvalds" tz="America/Sao_Paulo" />
    </>
  )
}

import { statsUrl } from '@gitwidgets/sdk'

const url = statsUrl({ username: 'torvalds', theme: 'glass' })
// → 'https://gitwidgets.dev/api/stats.svg?username=torvalds&theme=glass'

---

Development

Requirements: Node ≥ 20, pnpm ≥ 9

git clone https://github.com/gitwidgets-org/gitwidgets
cd gitwidgets
pnpm install

# Run everything in watch mode
pnpm dev

# Run only the Worker
cd apps/api && echo "GITHUB_TOKEN=ghp_..." > .dev.vars
pnpm wrangler dev --local
# → http://localhost:8787/api/stats.svg?username=torvalds

Common commands

pnpm dev          # start all apps in watch mode (api + dashboard + docs)
pnpm test         # vitest across all packages
pnpm typecheck    # tsc --noEmit
pnpm lint         # biome lint
pnpm format       # biome format
pnpm build        # turbo build

Monorepo layout

gitwidgets/
├── apps/
│   ├── api/          # Cloudflare Worker — public SVG API
│   ├── dashboard/    # Next.js — landing, playground, profiles, compare
│   └── docs/         # Nextra — technical docs site
└── packages/
    ├── core/         # Engine — domain, renderers, fetchers, themes, schemas
    ├── action/       # GitHub Action wrapper
    ├── sdk/          # JS/TS SDK
    ├── tsconfig/     # Shared TS configs
    └── biome-config/ # Shared Biome config

All business logic lives in packages/core. Apps are thin shells.

---

Roadmap

Phase	Title	Status
Phase 1	Foundation (monorepo, fetcher, core)	✅ Done
Phase 2	Stats widget (end-to-end)	✅ Done
Phase 3	Streak renderer + HTTP route	✅ Done
Phase 4	Core themes (light, glass, minimal)	✅ Done
Phase 4b	Extended themes (terminal, brutalist, synthwave, bauhaus, bloomberg, sticker)	✅ Done
Phase 5	Summary widget (top languages + pinned repos)	✅ Done
Phase 6	Infra — D1 migrations, Durable Objects, deploy CI	✅ Done
Phase 7	GitHub Action	✅ Done
Phase 8	JS/TS SDK	✅ Done
Phase 9	Dashboard MVP (landing, playground, profiles, compare)	✅ Done
Phase 10	Docs site (Nextra v3, 17 routes, live previews)	✅ Done
Phase 11	Auth (GitHub OAuth) + custom themes	⏳ Post-MVP

---

Documentation

Document	Description
.docs/CONTEXT.md	Live project state — read before any task
.docs/vision.md	Product vision and goals
.docs/architecture/README.md	System architecture
.docs/decisions/	ADRs — architectural decisions
.docs/tasks/	Task files per phase
.docs/api/endpoints.md	HTTP endpoint contracts
.docs/domain/	Domain rules per widget

---

Contributing

1. Fork → branch → PR against main
2. pnpm lint && pnpm typecheck && pnpm test must pass
3. One feature per PR; include or update tests
4. Run the core-guardian agent before opening a PR
5. Run the docs-keeper agent after merging

---

License

packages/core, apps/api, apps/docs, packages/action, packages/sdk — MIT
apps/dashboard — AGPL-3.0