Skip to content

Home

Jump to bottom
Ferran Buireu edited this page Jun 13, 2026 · 4 revisions

🟩 ContribKit

Visualize, customize, and export your GitHub contribution calendar — custom palettes, shapes, and backgrounds. No token required.

ContribKit turns any public GitHub profile into a fully customizable contribution calendar you can pin, embed, or carry on your home screen. It runs as a web app and public API on Cloudflare Workers, and as a native iOS & Android app with home-screen widgets — both sharing a single set of design tokens.

What It Does

  • Reads GitHub's public contributions page for any username — no API token, no OAuth, no private data
  • Parses it into a date / level / count model and builds a 53×7 calendar grid
  • Renders a customizable calendar as SVG (web/API), PNG, or Markdown (app)
  • Offers 11 color palettes, 5 cell shapes, and configurable backgrounds
  • Exposes a live SVG endpoint you can drop straight into a README
  • Ships a mobile app with daily-refreshed home-screen widgets

Quick Navigation

Page Description
Getting Started Render your first calendar, embed it, install the app
How It Works Request lifecycle, data pipeline, rendering
API Reference Endpoints, query params, response formats
Architecture DDD-ish layers, value objects, typed failures
Project Structure Monorepo layout: web, app, shared tokens
Web Application Astro on Cloudflare Workers — dev, deploy, env
Mobile App Flutter app, widgets, in-app purchases
Fetching Contributions The GitHub HTML scraping repository
HTML Parsing Regex extraction of cells and tooltips
Calendar Grid Building the deterministic 53×7 grid
SVG Rendering Geometry, shapes, and the string renderer
Deterministic Randomness The Mulberry32 PRNG used for placeholder grids
CI/CD Path-filtered workflows, environments, releases
Troubleshooting Common issues and fixes

Key Features

Customization

  • 11 palettes: GitHub, Catppuccin, Nord, Dracula, Gruvbox, Sunset, Tokyo Night, One Dark, Rosé Pine, Solarized, Monokai
  • 5 cell shapes: rounded, square, circle, dot, hex
  • Backgrounds: transparent, any hex color, or a CSS color name
  • Year selector: any year back to 2005 (GitHub's launch)

Platforms

  • Web app + API — Astro + TypeScript on Cloudflare Workers
  • iOS & Android — one Flutter codebase, platform-respecting home-screen widgets
  • README embed — a one-line Markdown snippet that always shows your latest calendar

Engineering

  • DDD-ish layered architecture shared by web and app (domain → application → infrastructure/ui)
  • Pure domain, validated value objects at every boundary, typed Failure unions — nothing throws across layers
  • Shared design tokens defined once in shared/, consumed by both apps
  • Per-component CI with path filters, per-PR preview deploys, semantic-release

Minimal Embed

![contributions](https://contribkit.app/user/YOUR_USERNAME.svg)

With options:

![contributions](https://contribkit.app/user/YOUR_USERNAME.svg?palette=catppuccin&shape=hex&background=transparent)

See Getting Started for the full walkthrough.

Links

License

MIT — Made by Ferran Buireu. ContribKit is not affiliated with GitHub, Inc.

Clone this wiki locally