GitHub Star Count Integration
Add live GitHub star counts to websites as social proof. Two patterns depending on traffic level — pick the right one and go.
Decision: Client-Side vs Server-Side
Client-side hook (default) — fetch directly from GitHub API in the browser.
- No API key needed for public repos
- GitHub allows 60 requests/hour per IP (unauthenticated)
- Fine for most sites — each visitor makes their own request
- Star count simply doesn't render if the fetch fails
Server-side caching — proxy through your own API route with a GITHUB_TOKEN.
- Raises the limit to 5,000 requests/hour
- Add
next: {revalidate: 300}to cache for 5 minutes - Use this for high-traffic pages or when you need the count at build time
Client-Side Hook
import { useEffect, useState } from "react";
export function useGitHubStars(repo: string) {
const [stars, setStars] = useState<number | null>(null);
useEffect(() => {
fetch(`https://api.github.com/repos/${repo}`)
.then((res) => res.json())
.then((data) => {
if (data.stargazers_count !== undefined) {
setStars(data.stargazers_count);
}
})
.catch(() => {}); // Intentional: star count is non-critical social proof — icon renders without it
}, [repo]);
return stars;
}Display Pattern
import { Github } from "lucide-react";
const stars = useGitHubStars("owner/repo");
<a
href="https://github.com/owner/repo"
target="_blank"
rel="noopener noreferrer"
className="inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-sm text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<Github className="h-4 w-4" />
{stars !== null && <span className="text-xs tabular-nums">{stars}</span>}
</a>Why tabular-nums: prevents layout shift as the digit count changes — all numerals occupy the same width.
Why stars!== null: the GitHub icon always renders; the count only appears after the fetch succeeds. If GitHub is down or rate-limited, the link still works as a plain GitHub link.
For More
Read references/patterns.md for:
- Server-side caching API route (Next.js)
- Mobile-responsive display (collapsed on small screens, badge on large)
- Rate limit details and when to add a token
- Animated star count (number counting up on mount)
- Reference implementation from our theme-token project