DEV Community

Cover image for gh-star-gif: Generate a 'Please star' GIF for any GitHub repo
Yuki Shindo
Yuki Shindo

Posted on

gh-star-gif: Generate a 'Please star' GIF for any GitHub repo

#github #gif

If you maintain open source projects, you have probably written some version of:

"Please consider starring this repo if it helps you."

It is totally normal. Stars help discoverability and social proof, but plain text is easy to skim past. Many people want to star your project, they just do not do it in that moment.

So I built a small tool to make the ask more visible (and a bit more fun).

It generates a short "please star" GIF from a repo URL, so you can drop it into your README or share it when you announce updates.

What is gh-star-gif?

gh-star-gif is a CLI tool that generates a short animated GIF from any GitHub repository page.

You pass a repository URL, run one command, and it produces a GIF that opens the repo page, highlights the Star button, moves a fake cursor toward it, and shows a callout like "Star this repo ⭐".

You can then embed the GIF in your README, docs, or social posts.

Demo

Try it now

The quickest way:

npx gh-star-gif https://github.com/shinshin86/gh-star-gif
Enter fullscreen mode Exit fullscreen mode

It will generate a GIF file in ./out/ by default.

Why this is useful for indie devs

When you are building in public, distribution matters. A README is often your landing page, and a single visual can do more than a paragraph of text.

A short "star highlight" GIF helps when:

  • someone lands on your repo from a tweet, a blog post, or Hacker News
  • your README is long and the call to star is buried
  • you are shipping small tools and want a lightweight way to promote them
  • you want a reusable promo asset for releases and announcements

This is not about spamming. It is about reducing friction for people who already found your project useful to star it.

Where to use it

It works best when placed where people make quick decisions:

  • near the top of your README (right after the project summary)
  • in release posts or changelogs when you announce updates
  • at the end of devlogs or tutorials that link to your repo
  • in social posts that drive traffic to GitHub

Prerequisites

This tool uses browser automation and video-to-GIF conversion, so you will need a couple of standard dependencies first:

  • Node.js 20+
  • ffmpeg available on your PATH
  • Playwright browser binaries installed

Install Playwright:

npx playwright install --with-deps chromium
Enter fullscreen mode Exit fullscreen mode

Install ffmpeg (examples):

  • macOS (Homebrew): brew install ffmpeg
  • Ubuntu: sudo apt-get install ffmpeg
  • Windows (Chocolatey): choco install ffmpeg

Usage examples

Basic usage 

npx gh-star-gif https://github.com/microsoft/TypeScript
Enter fullscreen mode Exit fullscreen mode

Custom message and output path 

npx gh-star-gif https://github.com/facebook/react \
  --message "If this helped, please star ⭐✨" \
  --out ./promo.gif
Enter fullscreen mode Exit fullscreen mode

Common tuning options 

npx gh-star-gif https://github.com/owner/repo \
  --out ./custom.gif \
  --message "Star this repo ⭐" \
  --width 1280 \
  --height 720 \
  --fps 15 \
  --scale 960 \
  --duration 4200
Enter fullscreen mode Exit fullscreen mode

Tip: If you want to debug what the browser sees, run with --debug. If you prefer watching the run, add --headful.

How it works under the hood (technical overview)

At a high level, gh-star-gif does this:

  1. Launches a headless Chromium session via Playwright
  2. Opens the target GitHub repository page
  3. Locates the Star button using multiple strategies (role, aria-label, form action)
  4. Injects an overlay (spotlight, pulsing ring, animated cursor, tooltip)
  5. Records the viewport as a short video
  6. Converts the video into an optimized GIF via ffmpeg using two-pass palette generation

This approach keeps the GIF consistent and readable while keeping the file size reasonable.

It is intentionally simple: render the real GitHub page, guide the viewer's eye to the Star button, and export a lightweight GIF you can embed anywhere.

A couple of design choices (and why)

I chose GIF because it is easy to embed almost anywhere and it draws attention without asking the reader to click or leave the page.

I used Playwright so the output reflects the real GitHub UI, which makes the guidance intuitive for first-time visitors.

The ffmpeg palette step is there to keep the result readable while staying reasonably small in file size.

Open source

Repo: https://github.com/shinshin86/gh-star-gif

If you try it and it helps, feedback and contributions are welcome.
And if you like the idea, you know what to do: ⭐

Top comments (0)