back to gh-widgets

Run your own

gh-widgets is one Cloudflare Worker plus a static site. There is no database and no secret to configure beyond an optional GitHub token. Fork it, deploy it, and your READMEs use a service only you control. It fits easily in Cloudflare's free tier.

1. Fork and clone

Fork hdprajwal/gh-widgets on GitHub, then clone your fork: 

git clone https://github.com/<you>/gh-widgets
cd gh-widgets
npm install

2. Run it locally

Two terminals. One runs the SVG worker, the other runs the site with hot reload; the site proxies image requests to the worker: 

npx wrangler dev   # the SVG API on :8787
npm run dev        # the site on :4321

Or build the site and serve everything the way production does, from one command: 

npm run preview

3. Deploy to Cloudflare

You need a free Cloudflare account. Before deploying, open wrangler.jsonc and remove the routes block. It points the worker at this site's domain, which your account does not own: 

// wrangler.jsonc: delete these lines in your fork
"routes": [
  { "pattern": "gh-widgets.hdprajwal.dev", "custom_domain": true }
],

Then log in, build, and deploy:

npx wrangler login
npm run build
npx wrangler deploy

The first deploy prints your URL: https://gh-widgets.<your-subdomain>.workers.dev. That is it. The site, the builders, and the SVG API are all live.

4. Recommended: GitHub token

The stars, license, and release badges call the GitHub API. Without a token, GitHub allows 60 requests an hour per IP, and Cloudflare's egress IPs are shared, so those badges will often show rate limited in production. Create a fine-grained token with "Public repositories (read-only)" access and no other permissions, then: 

npx wrangler secret put GITHUB_TOKEN

5. Optional: custom domain

If you have a domain on Cloudflare, add the routes block back with your own hostname and deploy again. Cloudflare creates the DNS record and the certificate for you: 

"routes": [
  { "pattern": "widgets.example.com", "custom_domain": true }
],

6. Use it in a README

Open a widget page on your deployed site, set it up in the builder, and copy the <picture> snippet it generates. GitHub shows the dark or light version to match each visitor's theme.

Good to know