Skip to content

Getting Started

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

Getting Started

There's nothing to install to use ContribKit — it works with any public GitHub username. Pick the path that fits you.

1. Use the web app

  1. Open contribkit.app.
  2. Type a GitHub username and hit render.
  3. Tweak the palette, shape, and background in the customizer.
  4. Pick a year (anything from 2005 to today) or keep the latest rolling year.
  5. Copy or export from the export section (PNG, SVG, or Markdown).

No login, no token — ContribKit only reads public contribution data.

What you can customize

Option Choices
Palette GitHub, Catppuccin, Nord, Dracula, Gruvbox, Sunset, Tokyo Night, One Dark, Rosé Pine, Solarized, Monokai
Shape rounded, square, circle, dot, hex
Background transparent, any hex (#101010), or a CSS color name
Year any integer from 2005 (GitHub's launch) to the current year

2. Embed it in your README

The simplest embed renders your calendar live every time someone views your profile:

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

With customization:

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

Unknown option values silently fall back to the default, so the image never breaks. See API Reference for every parameter.

3. Install the mobile app

  1. Install from Google Play (App Store coming soon).
  2. Enter your username.
  3. Add a widget to your home screen — small (streak counter), medium (full grid), or large (both).

Widgets refresh once a day in the background. See Mobile App for details.

4. Run it locally

ContribKit is a pnpm-workspace monorepo (web/, app/, shared/).

Prerequisites: Node v26.3.0 (see engines), pnpm@11.x, and — for the app — the Flutter SDK. Install lefthook once so the local checks fire.

To work on the web app:

pnpm install        # from the repo root
cd web
pnpm dev            # generates wrangler types, then starts Astro

To work on the Flutter app:

cd app
flutter pub get
flutter run --flavor development --dart-define-from-file=dart-defines.json

If you edit design tokens in shared/, run pnpm sync:assets so the app picks them up. See Project Structure, Web Application, Mobile App, and Git Hooks.

Next steps

Clone this wiki locally