A self-deployable Cloudflare Worker that generates and caches GitHub star-history SVG charts. It uses GitHub's privacy-safe star history API directly, so it does not depend on the Star History API or send a GitHub token to a chart SaaS.
For maintainers who want a cached, self-hosted chart: deploy Starfolio Worker in your own Cloudflare account and embed the generated SVG in your README. A GitHub token is optional but recommended for higher API rate limits.
Use Starfolio Worker when you:
- want a README chart for any public GitHub repository;
- have a Cloudflare account and can create a KV namespace;
- want a cached SVG without a third-party chart service or client-side JavaScript.
Charts use GitHub's weekly, privacy-safe star history data and do not expose stargazer identities.
- Add the repositories you want to track in
src/projects.js. - Create a Cloudflare KV namespace and add the GitHub Actions secrets and variables listed in the deployment guide.
- Push to
main, optionally run Sync Star Token once, then add the generated image URL to your README.
The full setup, including the least-privilege Cloudflare deployment token, is in docs/deploy.md. Read SECURITY.md before creating a GitHub token.
Starfolio Worker was originally inspired by Star History, including its hand-drawn chart visual language.
It began during the July 2026 stargazers API restriction, when per-stargazer timestamps became limited to a repository's administrators and collaborators. GitHub later added a privacy-safe, weekly star-history endpoint, which Starfolio Worker now uses. That means it can chart any public repository without a privileged token.
Deploying the Worker in your own Cloudflare account keeps chart generation and caching under your control, and public requests only receive the generated SVG. A GitHub token remains optional and is used only to raise API rate limits.
- Serves static SVG charts from Cloudflare KV.
- Refreshes configured repositories every hour with a Cloudflare Cron Trigger.
- Supports
lightanddarkthemes. - Uses GitHub's privacy-safe, weekly star-history API for public repositories of any size.
- Reduces each history to at most 18 plotted points for a consistent, smooth curve.
- Is deployable from GitHub Actions without committing Cloudflare IDs or tokens.
Use <picture> to automatically show the matching chart for a reader's light or dark system theme. Replace the Worker domain and project slug with your own values:
<a href="https://github.com/owner/repository">
<picture>
<source
media="(prefers-color-scheme: dark)"
srcset="https://your-worker.your-subdomain.workers.dev/star-history/project-slug?theme=dark"
/>
<source
media="(prefers-color-scheme: light)"
srcset="https://your-worker.your-subdomain.workers.dev/star-history/project-slug?theme=light"
/>
<img
alt="Star history chart"
src="https://your-worker.your-subdomain.workers.dev/star-history/project-slug?theme=light"
/>
</picture>
</a>| Request | Response |
|---|---|
GET / |
Health check: {"status":"ok"}. |
GET /star-history/{project} |
Light-theme SVG for a configured project. |
GET /star-history/{project}?theme=dark |
Dark-theme SVG. |
| Unknown route, project, or theme | 404 Not Found. |
When a configured chart has no cache entry yet, the Worker returns 503 with Retry-After: 10 and starts a background refresh. Retry shortly afterwards.
Edit src/projects.js to expose a project. Keys become URL path segments and values are GitHub owner/repository names.
export const projects = {
"opencode-models-discovery": "yuhp/opencode-models-discovery",
"another-project": "owner/another-project",
};The generated cache entries are:
star-history:{project}:light
star-history:{project}:dark
Each refresh reads repository metadata for its creation date and current total, then pages through the weekly star-history endpoint until it reaches the repository's first week. The per-day counts become a cumulative daily series, which is sampled at uniform time intervals across the repository's lifetime to preserve growth velocity. The final curve includes the repository creation point, 16 uniform time-interval samples, the latest known daily point, and the current total.
The star-history endpoint returns up to 30 weeks per page, newest first. A typical repository needs a handful of requests; even a repository spanning GitHub's full lifetime needs roughly 32. Anonymous requests are limited to 60 per hour per IP, so a token is recommended for scheduled refreshes.
Stars are plotted on the day they were received, not on the Sunday that starts their reporting week. If the latest known day already matches the current total, the curve extends flat to the current time; otherwise the small remaining rise is left at the end instead of being backdated.
-
Install dependencies:
npm install
-
Optionally create a local GitHub API token file:
cp .dev.vars.example .dev.vars
-
Set
GITHUB_TOKENin.dev.varsif you created the file. The token is optional for public repositories and needs no write access; it raises the GitHub API limit from 60 to 5,000 requests per hour. -
Copy the Cloudflare configuration template and fill in your Worker name and KV namespace ID:
cp wrangler.jsonc.example wrangler.jsonc
-
Start the Worker:
npm run dev
wrangler.jsonc and .dev.vars are ignored by Git and must not be committed.
The deployment workflow generates a temporary wrangler.jsonc from repository configuration and deploys the Worker. No deployment-specific IDs are committed to this repository.
See Deployment for the complete Cloudflare and GitHub setup, including least-privilege Cloudflare API Token permissions, KV creation, GitHub credentials, and verification.
Create these GitHub repository secrets:
| Secret | Purpose |
|---|---|
CLOUDFLARE_API_TOKEN |
Cloudflare API token with permission to deploy the target Worker. |
CLOUDFLARE_ACCOUNT_ID |
Target Cloudflare account ID. |
STAR_HISTORY_TOKEN |
Optional GitHub token written to the deployed Worker as its GITHUB_TOKEN runtime secret. It raises API rate limits and needs no write access. |
Create these GitHub repository variables:
| Variable | Purpose |
|---|---|
CLOUDFLARE_WORKER_NAME |
Name of the deployed Worker, for example starfolio. |
CLOUDFLARE_KV_NAMESPACE_ID |
ID of the KV namespace bound as KV_StarHistory. |
Push to main or run the Deploy Worker workflow manually. Pull requests and all pushes run type checks and tests without deploying.
Run the separate Sync Star Token workflow only after initially setting or rotating STAR_HISTORY_TOKEN. It writes that GitHub secret to the Worker as GITHUB_TOKEN without triggering a code deployment.
For a manual deployment, create wrangler.jsonc as above, authenticate with npx wrangler login, optionally set the production secret, then deploy:
npx wrangler secret put GITHUB_TOKEN
npm run deploySee docs/design.md for the request path, scheduled refresh flow, cache model, and failure behavior.
No. Starfolio Worker uses GitHub's privacy-safe weekly star-history endpoint, which works for public repositories without administrator or collaborator access. A token is optional; it raises the API limit from 60 to 5,000 requests per hour and makes scheduled refreshes more reliable.
Self-deploying keeps the repository list and any token under your control, and the public endpoint only serves cached SVG. It also avoids depending on a third-party chart service for data that GitHub now exposes directly. See SECURITY.md for token handling.
No. Public requests read a completed SVG from KV. The scheduled Worker job refreshes chart data hourly. On a first cache miss, the endpoint starts a background refresh and returns 503 with Retry-After: 10; it preserves the last successful chart if a later refresh fails.
npm run check
npm testStarfolio Worker is independent, does not call the Star History API, and is not affiliated with the Star History project.