FaizPalwala/serverless-github-calendar

Contribute to FaizPalwala/serverless-github-calendar development by creating an account on GitHub.

Summary

Serverless GitHub Calendar is a React component for displaying GitHub contribution heatmaps that sources its data from a scheduled GitHub Action rather than a runtime API call. The package is split into a GitHub Action that writes contribution data to your repository and a lightweight React component that renders a static JSON file. It is published under the MIT license and written in TypeScript.

What it is useful for

This package helps engineers who want a GitHub contribution heatmap on personal sites, portfolios, or profile READMEs without depending on third-party proxy APIs. The README notes that popular libraries like react-github-calendar rely on proxy services that suffer from rate limits and downtime, which can break portfolio sites. By moving the data fetch into a scheduled GitHub Action, the heatmap data is served as a static file from your own domain, so the component has no runtime dependencies or network calls in the request path.

It is also useful when you need the heatmap embedded in a GitHub profile README (via the documented SVG output mode) or rendered in a Next.js App Router page with zero client-side JavaScript using the included ServerHeatmap server component, which reads the JSON file directly from the server's filesystem.

How engineers can use it

The setup requires two parts: a workflow file in your site repository and the component itself.

1. Add the workflow at .github/workflows/contributions.yml:

name: Fetch Contributions
on:
  schedule:
    - cron: '0 */12 * * *'
  workflow_dispatch:
jobs:
  update-heatmap:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v7
      - uses: FaizPalwala/serverless-github-calendar/packages/[email protected]
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          username: your-github-username
          output-file: public/contributions.json
      - uses: stefanzweifel/git-auto-commit-action@v7
        with:
          commit_message: "chore: update github heatmap data"
          file_pattern: public/contributions.json

2. Install the component:

npm install serverless-github-calendar

3. Render it in a React, Next.js, or Astro project:

import { Heatmap } from 'serverless-github-calendar';
export default function Portfolio() {
  return <Heatmap />;
}

Theming is handled through CSS variables (--serverless-github-calendar-color-0 through -color-4), or by importing pre-packaged themes such as themes/dracula.css or themes/github-dark.css. The Action also exposes current and longest streak stats in the output JSON and SVG.

Documented limitations to keep in mind:

• Because data is static, your site must redeploy to reflect new contributions; the default 12-hour schedule triggers about 60 deploys per month, which the README notes consumes roughly 1% of Vercel's free tier.
• The default GITHUB_TOKEN only fetches public contributions; private contributions require a Personal Access Token with read:user scope stored as a repository secret.
• If you add [skip ci] to the auto-commit message to save build minutes, the heatmap will only refresh when other code changes are pushed.