react-github-calendar and the two packages behind a contributions grid

A wrapper around a grid and an API client

The package describes itself as a React component to display your GitHub contributions calendar, and the very next sentence tells you that it is built on two other packages: react-activity-calendar and github-contributions-api.

That is worth pausing on, because it determines what this package is for. The calendar you see on a GitHub profile is not something this library reimplements. The grid rendering comes from react-activity-calendar, and the data retrieval comes from github-contributions-api. What react-github-calendar adds is the wiring between them, configured so that you point it at a username and get the familiar green grid.

The public surface is correspondingly small. The usage section shows two lines of actual code:

import { GitHubCalendar } from 'react-github-calendar';

<GitHubCalendar username="grubersjoe" />

A username is the only required input, which is the point of the package. The alternative would be for every consumer to assemble the data fetching, the year selection, the colour theme and the tooltip behaviour themselves, and the value of this one is that the default configuration already matches what a GitHub profile looks like.

The package is TypeScript, MIT licensed, the default branch is main, and the last push was on 2026-10-21. Recent releases are v4.0 in April 2023, which brought dark mode and better tooltip support, v4.1.1 in January 2024 with improved error handling, and v5.0 in November 2025, with the manifest now at 5.0.9. The homepage is a demo and documentation site, and the repository is not archived.

Version 5 changed the API and the README points at the list

The README puts the version 5 announcement immediately after the intro, and it does not describe the changes inline. It links to the list of breaking changes on the v5.0 release page.

That is a deliberate choice and it is a good one for a component library. A major version means the API moved, and the readable place for that list is the release notes, where each change can be described in the context of the release. The README's job is to tell you the version exists and that you need to read the notes, which it does in one line.

The consequence for an adopter is that the README alone is not enough to evaluate an upgrade. If you are on v4, the v5.0 release notes are a prerequisite, not an optional extra.

The manifest shows how the version 5 surface is packaged. The exports map points the main entry at ./build/index.js and additionally exposes ./tooltips.css as a named export path, which tells you that the tooltip styling is a separate stylesheet the consumer has to import. The package is type module, so it ships as ESM, and the types entry points at build/index.d.ts.

That build/index.d.ts is not committed by hand. The typegen script uses dts-bundle-generator against src/index.tsx with the --no-check and --no-banner flags, and it runs as a postbuild hook, so the declarations are regenerated from the source on every build rather than maintained separately.

Server side rendering is supported, just not by this component

The FAQ answers the SSR question with a distinction that is easy to miss.

Server side rendering is supported, but not with this component, because it fetches data client-side. For SSR support, the guidance is to fetch the GitHub contribution data from a suitable API server-side and pass it on to the internally used react-activity-calendar component, and the README points at the source code as an example along with the GitHub colour theme.

So the component that actually renders the grid is the one you would use directly in a server rendered application, and react-github-calendar is the batteries-included version that also handles the fetching.

That split is a reasonable design, and it also tells you something about the dependency arrangement. The manifest lists react-activity-calendar as a runtime dependency and does not list github-contributions-api, which is consistent with the data layer being something the wrapper reaches for rather than something the consumer installs.

The practical advice for a team that renders a profile page on the server is straightforward: skip this package, use react-activity-calendar, and fetch the data yourself. The colour theme and the tooltip styling mentioned in the SSR answer are the parts worth carrying over, and the exported ./tooltips.css path is how you get the second one.

Create React App is not supported, and the reason is CRA itself

The second FAQ entry is the most opinionated thing in the README, and the reasoning is about the state of the ecosystem rather than about this package.

Create React App is considered abandoned, with a link to the discussion where that was concluded, and the recommendation is that you probably should not use it any more. The author states that using this component inside CRA will lead to errors, for reasons described in issue 105 of react-activity-calendar, and says plainly that this repository is not for CRA support questions: if you encounter issues you need to fix them yourself given the maintenance state of CRA.

The alternative recommended is Vite, on the grounds that it offers everything CRA does and more.

This is a rare and useful thing to find in a package README. A component that says it will not support a build tool, explains which of its own dependency is the reason, and points at the abandonment discussion, is telling you something precise: the errors you would hit are not the maintainer's problem to fix, because the tool underneath is no longer maintained either.

The practical advice for a team on CRA is not to fight it. Either migrate the build to Vite, which the author recommends and which removes the problem class entirely, or drop this component. There is no configuration that makes the combination work, and the README is explicit that questions about it will not be answered here.

The dev workflow builds the library and the example together

The development section is two commands and a URL:

pnpm install
pnpm dev

Open http://localhost:3000 afterwards. The dev script is where the shape of the project becomes visible, because it does three things in one go. It runs typegen to regenerate the type declarations, then build to produce the bundle, and then starts two watchers concurrently, one running rollup in watch mode and one starting the example app with --open.

The example application lives in the example directory and is a Vite project, with its own package.json, tsconfig.json, vite.config.mts, an index.html and a src directory. The repository also contains an example/docgen.sh script, and the deploy script publishes the example's build output with gh-pages, which is what produces the demo and documentation site at the homepage.

The package manager is pnpm, with a pnpm-lock.yaml and a pnpm-workspace.yaml at the root, and there is a .husky directory with a prepare script that installs the git hooks, a .npmignore for the published package contents, and an eslint configuration plus a prettier configuration that includes a plugin to sort imports.

The check script is the one worth noting for a contributor. It runs a frozen-lockfile install, then checks formatting with prettier, then the typecheck, then the lint, and the prepublishOnly hook runs that check and the build before anything is published. So the same command that gates a release is the local verification command, and it covers formatting, types and lint in that order.

Where react-github-calendar is the wrong tool

The first wrong case is a server rendered application, and the FAQ says so plainly. The component fetches data client-side, so on a server rendered page it will render nothing useful on the first pass, and the fix is to use react-activity-calendar with data you fetch yourself. The package is not broken here, it is doing what it does, and it is simply the wrong layer for that rendering model.

The second wrong case is a Create React App project. The author has declined to support it, has explained which dependency causes the failure, and has said that CRA support questions are out of scope. If you cannot migrate your build, then you cannot use this component, and the FAQ is clear that this is not negotiable.

The third wrong case is a product that wants a different visual language. The package's default is the GitHub colour theme, which is what makes the component useful with no configuration, and it also ships the tooltip stylesheet as a separate export path. If you want your own palette, you are fighting the defaults, and at that point react-activity-calendar, which this package wraps, is the more direct dependency.

The alternative worth naming is react-activity-calendar itself, and the difference in approach is the wrapper versus the component. The lower-level package gives you a grid you can point at any data source, including data you already have from your own API, and it is what you would reach for in a server rendered app, in a design system with its own colours, or if you want to display something that is not a GitHub account. react-github-calendar takes that component and hardens the default path for the specific case of showing a GitHub profile, including the fetching and the theme. If your use case is exactly a GitHub profile, the wrapper saves you the assembly. If it is anything adjacent, the underlying component is the one to depend on, and you gain the freedom to bring your own data and your own styling.

Maintenance state and the licence

The repository is not archived and the last push was on 2026-10-21, so the work is current. The release history shows a major version every couple of years, v4.0 in April 2023, v5.0 in November 2025, with the manifest currently at 5.0.9, which suggests a patch line that is being maintained inside the v5 series.

The version 5 announcement in the README is still the newest thing in it, alongside the demo and documentation links and the two FAQ entries. That is a thin README for a component with a breaking release, and it means the release notes on the v5.0 tag are where the real change documentation lives. For a library whose main cost to a consumer is a migration, that is worth noting.

The licence is MIT, with the LICENSE file at the repository root and the manifest recording the same identifier, so the package can be used in a commercial product without obligations beyond the notice. The author is Jonathan Gruber, and the package is published on npm as react-github-calendar with a CI badge for the test workflow and a demo site that doubles as the documentation.

The one thing to watch on the dependency side is react-activity-calendar, pinned in the manifest at a caret range of 3.1.2. Since the grid rendering, the tooltip behaviour and the GitHub colour theme all come from that package, a major version of it is the realistic source of a breaking change in your application, and this repository's own v5 release is the version where that coupling was last renegotiated.

Editorial conclusion

react-github-calendar fits a React project that wants a contribution grid for a user profile with the fetching already handled and the theme following GitHub's own colours. It is the wrong choice if you need server side rendering, since the component fetches data client-side and the README routes that case to react-activity-calendar directly, and the wrong choice inside a Create React App project, which the author explicitly declines to support. Before you adopt it, read the version 5 breaking changes, check that your project is on a bundler that handles the package's ESM export map, and decide whether you need the GitHub colour theme or your own.

Frequently asked questions

Official sources

1. grubersjoe/react-github-calendar on GitHub
2. License: MIT
3. Project website
4. README
5. Releases