Table of contents
GitHub readme files are an excellent way to convey information about a project's structure, help, patches, updates, and more. But readme images can be used for more fun stuff, like the GitHub profiles you see are basically readme files with some rich and often dynamic text and images.
Now that you have an idea of what readme images are, let's look at how I created a dynamic readme image that changes based on my GitHub activity. this article looks at the technical aspects and is not a step-by-step guide on creating it. with that said, the source code is on my GitHub in case you want to have a deeper dive into how things work.
Project Idea
My idea for this project was to create customized Github weekly stats, or some sort of fun, gamified way of displaying my GitHub activity. the aim was to encourage me to push more code to GitHub while having fun and a feeling of achievement in the whole process. When I commit code and do activities on GitHub, all of this is used to generate weekly points which increase the percentage on each level and will eventually help me clear a level. when I don't commit code, the percentage for a level drops by a given amount and I eventually drop in levels. this gave me the motivation to do more activities on GitHub, with me often being excited to see how much my percentage has advanced.
Architecture
How it works
A Nodejs script that fetches commits from the last 1 week from the GitHub API(excluding Github action commits) and updates the health and current level based on that. This script then runs every 7 days using GitHub action.
To generate the image, there is a template built with Tailwindcss in a Nextjs API route that uses vercel-og to generate the image. it simply uses query params passed, to get the current level, health, and commits and give back the corresponding image
challenges
one major challenge I faced was the image failing to load or loading very late after the readme has displayed. the initial approach I took was to embed the link to the Nextjs backend directly in the readme file, hence when I fetch updated GitHub data, I just update the query params, coursing a new image to be fetched..this coursed a major problem since the image usually delays to fetch and might often fail.
solution
I fixed this by fetching and storing the image locally in the project repo and just referencing this in my readme file. this reduced the delay of waiting for my image to fetch after my readme file has fully rendered
conclusion
With this, I am able to generate my weekly Github stats as a dynamic readme image, making it a more exciting experience to commit code to GitHub. below are links to the Nextjs API route repo and the main repo which contains the majority of the logic