@nannoy/git-folio

Embeddable GitHub stats card for developer portfolios. No API token required — works entirely with public GitHub data.

Install

npm install @nannoy/git-folio

Quick Start — Vanilla JS

import { fetchGitHubStats } from "@nannoy/git-folio";

const stats = await fetchGitHubStats({ username: "torvalds" });

console.log(stats.totalStars);            // number
console.log(stats.totalCommits);          // number (from GitHub Search API)
console.log(stats.topLanguages);          // LanguageStat[]
console.log(stats.contributionStreak);    // number — consecutive days
console.log(stats.contributionCalendar);  // ContributionWeek[]

React Component

import { GitFolioCard } from "@nannoy/git-folio/react";

export default function Portfolio() {
  return (
    <GitFolioCard
      username="torvalds"
      theme="auto"
      variant="full"
      accentColor="#2dd4bf"
    />
  );
}

How it works (no token)

All data is fetched from public GitHub endpoints in parallel:

Data	Source
Profile, repos, stars, forks, followers	GitHub REST API (`/users/{u}`, `/users/{u}/repos`)
Top languages + colors	REST repos list + bundled color map
Commit count	GitHub Search API (`/search/commits?q=author:{u}`)
PR count	GitHub Search API (`/search/issues?q=author:{u}+type:pr`)
Issue count	GitHub Search API (`/search/issues?q=author:{u}+type:issue`)
Contribution heatmap, streak	github-contributions-api.jogruber.de

Rate limits (unauthenticated):

REST API: 60 requests/hour per IP
Search API: 10 requests/minute per IP (separate bucket)
Contributions proxy: cached 1 hour

For server-side rendering, cache the result and revalidate on a schedule — the built-in cache option handles this: fetchGitHubStats({ username, cache: 3600 }).

React Props

Prop	Type	Default	Description
`username`	`string`	required	GitHub username
`theme`	`'light' \| 'dark' \| 'auto'`	`'auto'`	Color theme — `auto` follows system preference
`variant`	`'compact' \| 'full'`	`'full'`	`compact` shows avatar, name, and 4 key stats only
`accentColor`	`string`	`#2dd4bf`	Hex color for accents and heatmap tint
`showContributions`	`boolean`	`true`	Show contribution heatmap
`showLanguages`	`boolean`	`true`	Show top languages bar
`className`	`string`	—	Extra CSS class on the card element

GitFolioStats type

interface GitFolioStats {
  name: string;
  login: string;
  avatarUrl: string;
  bio: string | null;
  location: string | null;
  websiteUrl: string | null;
  followers: number;
  following: number;
  totalRepositories: number;
  totalStars: number;
  totalForks: number;
  totalCommits: number | null;      // null only if Search API rate-limited
  totalPullRequests: number | null; // null only if Search API rate-limited
  totalIssues: number | null;       // null only if Search API rate-limited
  totalContributions: number;
  topLanguages: LanguageStat[];
  contributionStreak: number;
  contributionCalendar: ContributionWeek[];
}

Error Handling

import { fetchGitHubStats, GitFolioError } from "@nannoy/git-folio";

try {
  const stats = await fetchGitHubStats({ username });
} catch (err) {
  if (err instanceof GitFolioError) {
    console.error(err.code);        // 'RATE_LIMITED' | 'USER_NOT_FOUND' | 'NETWORK_ERROR' | ...
    console.error(err.retryAfter);  // Date | undefined
  }
}

Error code	Cause
`RATE_LIMITED`	GitHub REST API rate limit hit
`USER_NOT_FOUND`	Username doesn't exist on GitHub
`NETWORK_ERROR`	DNS / fetch failure
`HTTP_ERROR`	Non-200 GitHub API response
`PARSE_ERROR`	Unexpected response body

Theming

CSS custom properties can be overridden on any ancestor:

.my-portfolio {
  --gf-accent: #a78bfa;
  --gf-accent-rgb: 167, 139, 250;
  --gf-radius: 12px;
  --gf-font: "Inter", sans-serif;
}

License

MIT — github.com/Nannoy/git-folio