DEV Community

Spec
Spec

Posted on

I Built an API That Turns Your GitHub Contributions Into a 3D Isometric Graph

#news #opensource #showdev #github

Your GitHub contribution graph is flat and green. Mine is an isometric skyline.

I built Isometric Contributions — a free API that renders your GitHub activity as a 3D isometric city, ready to drop into your README or portfolio with a single <img> tag.

Project Links:

  • Github Repo: LINK
  • URL Builder and Docs site: LINK

What it looks like

Sample:
Main Example Image

It also comes with six themes, all generated server-side as crisp PNG images:

All Designs

  • github - Classic green on dark
  • dark - Sleek dark palette
  • light - Clean white background
  • neon - Cyberpunk glow
  • minimal - Quiet and understated
  • ocean- Deep blue tones

You can also add a stats overlay showing your total contributions, current streak, longest streak, best day, and daily average — all baked right into the image.

Using it in 30 seconds

Drop this into your GitHub profile README and you're done:

![My Contributions](https://https://isometric-contributions-spectrewolf8.onrender.com/api/graph?username=YOUR_USERNAME&theme=dark&stats=true)
Enter fullscreen mode Exit fullscreen mode

That's it. No tokens, no setup, no dependencies on your end.

All the options 

GET /api/graph
Enter fullscreen mode Exit fullscreen mode
Parameter Default Description
username required Your GitHub username
theme github github · dark · light · neon · minimal · ocean
year none Specific year like 2024, or none for the last 365 days
stats false Set to true to include the stats overlay
credit false Set to true to show your username watermark
width 1000 Image width in px
height 600 Image height in px

Some examples:

# Last 365 days, neon theme, with stats
/api/graph?username=torvalds&theme=neon&stats=true

# Specific year, wide format
/api/graph?username=torvalds&year=2023&width=1400&height=700

# Minimal, no extras
/api/graph?username=torvalds&theme=minimal
Enter fullscreen mode Exit fullscreen mode

How it works under the hood

The stack is intentionally small — no framework, just Node.js.

Data: GitHub's official GraphQL contributionsCollection API. Each query fetches up to 365 days of contribution data with contribution counts, levels, and dates. Requests retry automatically up to 3 times with exponential backoff.

Rendering: obelisk.js handles the isometric projection math, running inside a JSDOM environment on the server. node-canvas provides the actual pixel buffer. Each day becomes a cube whose height is proportional to that day's contribution count.

Caching: Generated images are cached in Supabase Storage keyed by date/username/params. The same image is served instantly on repeat requests throughout the day without hitting the GitHub API or re-rendering. Images with suspiciously low data (a signal the API returned partial results) are intentionally not cached, so the next request gets a fresh attempt.

Output: A raw PNG buffer streamed directly as the HTTP response with Content-Type: image/png — which is exactly what <img src="..."> expects.

Self-hosting

Want to run your own instance?

git clone https://github.com/Spectrewolf8/isometric-contributions-embeds
cd isometric-contributions
npm install
Enter fullscreen mode Exit fullscreen mode

Set up your .env:

GITHUB_TOKEN=ghp_yourtoken        # PAT with no scopes needed for public data
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_ANON_KEY=your_anon_key
SUPABASE_BUCKET_NAME=isometric-cache
Enter fullscreen mode Exit fullscreen mode 
npm run server
Enter fullscreen mode Exit fullscreen mode

On startup, the server verifies your GitHub token and prints which account it's authenticated as, so you know immediately if something's wrong.

Deploy to Render, Railway, or any Docker-capable host — a Dockerfile is included.

What's next

A few things I want to add:

  • SVG output so the graph can scale infinitely
  • Custom color schemes via query params instead of fixed themes
  • Animated version — a time-lapse that builds the city week by week

If any of those sound useful to you, or if you would like to add anything else, leave a comment — it helps me prioritize.

Built with Node.js, obelisk.js, node-canvas, and Supabase. Contributions welcome.

Top comments (0)