@raulcanodev/react-github-dots

React GitHub Dots

Hey! This is a React component that creates the GitHub's green dots contribution graph. Perfect for spicing up your portfolio or tracking activity in a visually appealing way!

About this package

• Beautiful GitHub-style contribution visualization
• Seamless light and dark mode support
• Make it yours with custom color schemes
• Real-time GitHub data at your fingertips
• Looks great on any screen size
• ️ Smart caching for optimal performance

Getting Started

1. Pop this into your terminal:

npm install @raulcanodev/react-github-dots

1. Within your React app:

import ContributionGraph from '@raulcanodev/react-github-dots';

function App() {
  return (
    <ContributionGraph 
      username="your-github-username"
      token="your-github-token"
      theme="dark" // or "light"
      cacheTime="8h" // Cache data for 8 hours
    />
  );
}

For Next.js 13+ (App Router), add the client directive:

'use client';
import ContributionGraph from '@raulcanodev/react-github-dots';

export default function Page() {
  return (
    <ContributionGraph 
      username="your-github-username"
      token="your-github-token"
      theme="dark"
      cacheTime="1d"
    />
  );
}

Configuration Options

Here's what you can tweak:

Prop	Type	Default	What it does
username	string	required	Your GitHub username
token	string	required	Your GitHub access token
theme	'light' | 'dark'	'dark'	Pick your style
customColorScheme	object	null	Custom colors
loadingComponent	ReactNode	null	Custom loading state
cacheTime	false | '2h' | '8h' | '1d'	'1d'	Control data caching duration

Customize The Dot Colors

Want your own color scheme? Here's how:

<ContributionGraph 
  username="your-github-username"
  token="your-github-token"
  customColorScheme={{
    0: '#ebedf0', // No contributions
    1: '#ff9b9b', // 1-3 contributions
    2: '#ff4040', // 4-6 contributions
    3: '#ff0000', // 7-9 contributions
    4: '#990000'  // 10+ contributions
  }}
/>

️ Cache Control

Optimize performance with smart caching:

// Disable caching - always fetch fresh data
<ContributionGraph 
  username="your-github-username"
  token="your-github-token"
  cacheTime={false}
/>

// Cache for 2 hours
<ContributionGraph 
  username="your-github-username"
  token="your-github-token"
  cacheTime="2h"
/>

// Cache for 8 hours
<ContributionGraph 
  username="your-github-username"
  token="your-github-token"
  cacheTime="8h"
/>

// Cache for 1 day (default)
<ContributionGraph 
  username="your-github-username"
  token="your-github-token"
  cacheTime="1d"
/>

Development & Contributions

Getting Set Up

1. Grab the code:

git clone https://github.com/raulcanodev/react-github-dots.git
cd react-github-dots

1. Install what you need:

npm install

1. Build it:

npm run watch

Testing Locally

1. Link your package locally, which allows you to test it in other projects:

npm link

1. Create a new React app and link the component:

npx create-react-app test-github-dots
cd test-github-dots
npm install react react-dom
npm link @raulcanodev/react-github-dots

1. In your App.jsx, import and use:

import ContributionGraph from '@raulcanodev/react-github-dots';

Development Flow

Want to see changes in real-time? Here's how:

1. In your package directory:

npm run watch

1. In your test app:

npm run dev

Need to refresh the link for any bug? Try:

npm unlink @raulcanodev/react-github-dots
npm link @raulcanodev/react-github-dots

Getting Your GitHub Token

You'll need a GitHub Personal Access Token with read:user scope. Get one here: https://github.com/settings/tokens?type=beta

License

MIT Raul Cano

---

Made with by Raul Cano. Questions? Issues? Feel free to reach out!

Want to contribute? PRs are always welcome!