Escaping Rate Limits: Building a Serverless GitHub Calendar

August 30, 2026[Tech]

If you’ve ever built a developer portfolio, you’ve probably wanted to embed your GitHub contribution heatmap. The classic way to do this was using react-github-calendar or ghchart.

But there was a glaring, fatal architectural flaw with those libraries. GitHub’s API requires a Personal Access Token (PAT) for authentication, which you obviously can’t expose in frontend code. To bypass this, legacy plugins route all traffic through a third-party public proxy server.

This is essentially a frontend hack. When 100,000 developers embed a client-side fetch to the same free proxy server, that server gets rate-limited by GitHub. The result? Your portfolio randomly crashes, you get ugly loading spinners, or your heatmap renders as a blank square.

I got tired of my portfolio breaking because someone else’s server went down. So I completely rebuilt the architecture from scratch to create a robust, server-first data pipeline: Serverless GitHub Calendar.

The “Aha!” Moment

I realized that the GitHub GraphQL API can be queried directly from GitHub Actions. Since GitHub Actions are completely free for public repositories, why not just build an automated data pipeline directly into the user’s repository?

I engineered an architecture that works like this:

  1. A GitHub Action runs on a cron schedule (0 */12 * * *).
  2. It hits the GraphQL API with the user’s token, fetching the raw heatmap and streak statistics.
  3. It compiles that data into a hyper-optimized contributions.json payload.
  4. It commits that JSON file directly into the repository’s public/ folder.

Zero Runtime Overhead

Because the JSON is now sitting perfectly statically inside the public folder, the React component (or Next.js Server Component) never has to hit a third-party server. It just loads local data.

For Next.js App Router, I even wrote a ServerHeatmap component that uses fs.readFileSync() to parse the data during Server-Side Rendering. The final output sent to the browser is a pure SVG with zero bytes of client-side JavaScript.

Private Contributions Solved Safely

The best part about this architecture is that it elegantly solves the “Private Contributions” dilemma. Normally, to show private commits on a portfolio, you have to expose a Personal Access Token (PAT) somewhere vulnerable.

With this serverless setup, the PAT is stored securely as a GitHub Secret. The Action runs inside GitHub’s secure boundary, aggregates the data into numerical counts (e.g. 12 commits), and only ships the raw numbers. The token never touches the browser.

The library is live on NPM today. It’s time to stop letting free proxies ruin your portfolio.