gitvis

An interactive treemap of your GitHub starred repositories — finally see what you've been saving.

GitVisual rendering the current public starred repositories for beme08.

What it does

• Renders your starred repos as a treemap sized by stargazer count (log-scaled so megarepos don't dominate), colored by language
• Filter by language and topic, search by name/description/topic
• Click any tile to open the repo on GitHub
• Ships with a committed demo dataset so the page works on a fresh clone with zero setup
• Optional "Sign in with GitHub" automatically loads any visitor's public stars — no tokens ever touch the browser or localStorage

Quick start (just want to see the demo)

npm ci
npm run dev

Open http://localhost:4321. The page labels the committed src/data/stars-beme08.json snapshot as Demo data.

Use your own stars as the demo

# 1. Create a token at https://github.com/settings/tokens (no scopes needed for public stars)
export GITHUB_TOKEN=ghp_xxx
# 2. Fetch your stars
npm run fetch:stars -- your-username
# 3. Edit src/pages/index.astro to point at your new file, or replace stars-beme08.json

"Sign in with GitHub" (optional)

Without this, the demo works fine for any visitor — the committed data is shown. After sign-in, the page automatically replaces it with the visitor's current public stars and labels the result Live GitHub data. Refresh stars reloads the data on demand.

Setup (one-time per self-hoster)

1. Register a GitHub App using the exact GitVis settings
   • Application name: anything (e.g. gitvis (local))
   • Homepage URL: http://localhost:4321 (or your deployed URL)
   • Authorization callback URL: http://localhost:4321/api/auth/callback (must match exactly)
2. Copy .env.example to .env and fill in:
   • APP_ORIGIN — the exact origin where gitvis runs, without a trailing path
   • GITHUB_APP_CLIENT_ID — the GitHub App client id (not its app id)
   • GITHUB_APP_CLIENT_SECRET — a client secret generated for the GitHub App
   • SESSION_SECRET — generate with node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
3. Restart npm run dev

The public-stars viewer requests no repository, organization, or account data permissions. It validates state, uses PKCE, and requires expiring user tokens. It does not need to be installed on a repository. We never see private starred repositories, never write anything, and access and refresh tokens stay on the server. See SECURITY.md for the full threat model.

To revoke access, go to https://github.com/settings/applications.

Production deployment

gitvis is an Astro SSR application, not a static GitHub Pages site. The OAuth callback, server-side token exchange, session store, and starred-repository API all require the standalone Node server.

The included render.yaml deploys one Docker web service in Frankfurt. Render generates SESSION_SECRET; enter the GitHub App client ID and client secret when creating the Blueprint. After deployment, set the GitHub App homepage to https://gitvisual.onrender.com and its callback to https://gitvisual.onrender.com/api/auth/callback.

Required production variables:

Variable	Requirement
APP_ORIGIN	Exact public HTTPS origin, for example https://gitvis.example.com
GITHUB_APP_CLIENT_ID	GitHub App client id, not app id
GITHUB_APP_CLIENT_SECRET	GitHub App client secret
SESSION_SECRET	At least 32 random characters

Build, verify, and run directly:

npm ci
npm run check
NODE_ENV=production HOST=0.0.0.0 PORT=4321 node ./dist/server/entry.mjs

Or build the included container:

docker build -t gitvis .
docker run --rm -p 4321:4321 --env-file .env.production gitvis

Use /api/health/live for liveness and /api/health/ready for readiness. The readiness endpoint returns 503 until all four required production variables are valid.

The deployment target is one Node process on Render. Platform-specific serverless adapters are not configured in this repository.

Sessions last one hour and are held only in process memory. Star results are cached per session for 60 seconds, and repeated refreshes are throttled. A restart signs everyone out. Before running multiple instances, replace the in-memory store in src/server/session.ts with Redis or a KV client.

Public-launch checklist

• Create the public GitHub repository and enable private vulnerability reporting.
• Register the production GitHub App callback as APP_ORIGIN/api/auth/callback.
• Store the GitHub App client secret and session secret in the hosting provider, never in the repository.
• Keep the MVP at one instance and terminate TLS at the hosting provider.
• Verify authorization, load-stars, cache/throttle, logout, expiry, refresh, and revocation with two test users.

Tech

• Astro (server output, Node adapter)
• D3 (d3-hierarchy for the treemap, d3-scale for sizing/coloring)
• Octokit for the OAuth flow and data fetch
• No CSS framework, no React, no UI library — just SVG and a single CSS file

Tests

npm test

The dependency-free Node suite covers separate user identities, pagination, empty public-star lists, GitHub API errors, signed-session tampering, per-session refresh throttling, logout, and cross-user cache isolation. npm run check runs the tests, production build, and HTTP smoke checks together.

Contributing

See CONTRIBUTING.md. Issues and PRs welcome.

License

MIT — see LICENSE.