@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