GraphQL Fetcher
Hits the GitHub GraphQL API to pull your full contribution calendar — no scraping, no rate-limit hacks.
A tiny, headless npm package that fetches your GitHub contribution data via the GraphQL API and renders it as a heatmap using a zero-dependency React component.
npm install @achrekarom/github-contribution-chartHits the GitHub GraphQL API to pull your full contribution calendar — no scraping, no rate-limit hacks.
Zero-dependency component. Drop it in any React ≥ 17 project. Full SSR & Next.js Server Components support.
Bundled type declarations for every export. Enjoy full IntelliSense with zero extra configuration.
Override colors per-level, choose dark/light palette, control gap, cell radius, and month window.
Install via your favourite package manager. React is a peer dependency and only required if you use the chart component.
# Install the library
npm install @achrekarom/github-contribution-chart
# React peer dependency (if not already installed)
npm install reactyarn add @achrekarom/github-contribution-chartpnpm add @achrekarom/github-contribution-chartCall fetchGitHubContributions with a GitHub username and a PAT token. Works in Node.js, server components, and the browser.
import { fetchGitHubContributions } from 'github-contribution-chart';
// Token is read from options.token, or process.env.GITHUB_TOKEN
const calendar = await fetchGitHubContributions('achrekarom', {
token: process.env.GITHUB_TOKEN,
});Pass the calendar to <GitHubContributionChart>. Choose a colour scheme, set how many months to show, and you're done.
import { GitHubContributionChart } from 'github-contribution-chart';
export default function MyPage() {
return (
<GitHubContributionChart
calendar={calendar}
colorScheme="dark"
months={6}
/>
);
}Fetch and render in one async server component — no client state, no loading spinners.
import {
fetchGitHubContributions,
GitHubContributionChart,
} from 'github-contribution-chart';
export default async function Page() {
const calendar = await fetchGitHubContributions('achrekarom');
return (
<div style={{ width: '100%', height: 120 }}>
<GitHubContributionChart calendar={calendar} colorScheme="dark" />
</div>
);
}fetchGitHubContributions(username, options?)
async function
Hits the GitHub GraphQL API and returns the full contribution calendar for the given user, or null on error.
| Parameter | Type | Description |
|---|---|---|
username | string | GitHub username |
options.token | string | GitHub PAT with read:user scope. Falls back to process.env.GITHUB_TOKEN. |
options.fetchFn | typeof fetch | Custom fetch impl for Node <18 or test mocking. |
Promise<ContributionCalendar | null><GitHubContributionChart>
React component
Zero-dependency heatmap grid. Renders the contribution data from fetchGitHubContributions.
| Prop | Type | Default | Description |
|---|---|---|---|
calendar | ContributionCalendar | null | — | Data from the fetcher |
colorScheme | 'dark' | 'light' | 'dark' | Built-in GitHub-style palettes |
months | number | 6 | Recent months to display |
colors | Partial<Record<0|1|2|3|4, string>> | — | Override per-level colours |
gap | number | 4 | Cell gap in px |
cellRadius | number | 3 | Border-radius in px |
className | string | — | Wrapper CSS class |
style | CSSProperties | — | Wrapper inline styles |
TypeScript types
exported
ContributionCalendar
{ totalContributions: number; weeks: ContributionWeek[] }
ContributionWeek
{ contributionDays: ContributionDay[] }
ContributionDay
{ contributionCount: number; date: string }
ContributionLevel
0 | 1 | 2 | 3 | 4
ColorScheme
'dark' | 'light'
Create a fine-grained personal access token at github.com/settings/tokens with read-only access to your public data (read:user scope). Then set it as an environment variable:
export GITHUB_TOKEN=ghp_yourtokenAn interactive preview rendered entirely in the browser — no server required.