How sherdotsh/sher works
This repo is a developer CLI + serverless backend that creates instant preview links for static frontends.
• Client-side component: sher CLI (published as shersh on npm) that:
• detects framework/package manager
• builds (or skips build)
• collects static output files
• uploads to a hosted API
• returns a shareable URL (optionally TTL / password tier)
• Backend component: Cloudflare Worker + R2 + KV that:
• authenticates users via GitHub OAuth
• stores deployment metadata (IDs, TTL, ownership, tier, etc.)
• stores uploaded artifacts in R2
• serves preview URLs back to browsers
• optionally integrates Polar for paid “Pro” subscriptions
• Ancillary: agent “skill” docs (skills/, .agents/skills/) and packaging (Formula/ for Homebrew).
2) Map the file tree to architectural components (how to “separate into as many components as possible”)
CLI (Node/TypeScript) — src/
• src/index.ts: CLI entrypoint / command routing (likely sher link/list/delete/login/...)
• src/detect.ts: framework & package manager detection (Vite/Next/Astro/CRA/etc.)
• src/build.ts: runs the build command (e.g., npm run build)
• src/static-export.ts: Next.js static export logic (special-case)
• src/collect.ts: enumerates build output dir, file list, sizes
• src/upload.ts: upload client to Worker API (multipart or batched)
• src/api.ts: HTTP client wrapper + endpoint definitions (link/list/delete/whoami/upgrade)
• src/auth.ts: GitHub login flow (device flow or OAuth via Worker), token storage
• src/clipboard.ts: copies returned URL
• src/constants.ts: default API URL, directories, limits, etc.
Build/packaging for CLI:
• tsup.config.ts, tsconfig.json: compile/bundle
• package.json, package-lock.json: runtime deps, bin entry
Worker backend (Cloudflare) — worker/
Treat this as the “server” / API + static serving plane.
• worker/src/index.ts: Worker router / fetch handler (API + website pages)
• worker/wrangler.toml: binds R2 bucket, KV namespace, routes, env vars
• worker/lifecycle.json: hints about lifecycle/cron/maintenance (include if used)
• Website/marketing/blog pages are also in Worker:
• worker/src/landing.ts, pricing.ts, why.ts, blog.ts, plus many blog-*.ts
Backend integrations (from README; show as external systems):
• GitHub OAuth: callback /auth/callback (or similar)
• Polar (optional): webhook + product config for Pro
Storage & delivery plane (Cloudflare-managed)
• R2 bucket (e.g., sher-uploads): stores uploaded build artifacts
• Cloudflare edge routing: https://<id>.sher.sh resolves to Worker; Worker reads from R2 and returns static assets
Distribution / “installation”
• npm: package shersh
• Homebrew: Formula/sher.rb
• “Agent skill” docs: skills/sher-deploy/SKILL.md and .agents/skills/... (integration guidance for AI agents)
Worker writes
• artifacts → R2
• deployment metadata (owner, expiry, size, flags like password-protected) → KV
Worker
• looks up deployment metadata in KV (validate TTL, password requirement)
• fetches asset from R2
Flow 3: sher list / sher delete
• CLI calls Worker API endpoints
• Worker queries KV (and possibly R2) and returns deployments / deletes artifacts + metadata
Flow 4: Upgrade / Pro billing (optional branch)
• CLI calls Worker “upgrade” endpoint
• Worker interacts with Polar
• Polar sends webhooks back to Worker to confirm subscription state
• Worker updates user tier/quota in KV
System Context (Level 1): one-page overview
• Actors: “Developer (CLI user)”, “Recipient (browser viewer)”
• Systems: “Sher CLI”, “Sher Cloudflare Worker”, “GitHub OAuth”, “Polar (billing)”, “Cloudflare R2”, “Cloudflare KV”
• CLI subcomponents: Detect/Build/Collect/Upload/Auth
• Worker subcomponents: API router, Auth handler, Upload handler, Preview serving handler, Billing webhook handler
• Storage: R2 (artifacts), KV (metadata/state)
This matches the repo layout cleanly: src/* maps to CLI containers; worker/src/* maps to Worker containers.
Must-have labels (use exact tech names)
• “CLI (Node.js + TypeScript)”
• “Cloudflare Worker (TypeScript)”
• “Cloudflare R2 (artifact storage)”
• “Cloudflare KV (metadata/session/quota store)”
• “GitHub OAuth (identity)”
• “Polar (billing, optional)”
• “Preview URL: https://{id}.sher.sh (served by Worker)”
• “Env override: SHER_API_URL” (important architectural switch for self-hosting)
• CLI → Worker: “HTTPS API (upload, list, delete, whoami, upgrade)”
• Worker → R2: “PUT/GET artifacts”
• Worker → KV: “deployment metadata, TTL, auth state, tier/quota”
• Worker ↔ GitHub: “OAuth redirect + token exchange”
• Worker ↔ Polar: “create checkout / verify” and “webhook events”
• Browser → Worker: “GET / (static assets)”
Deliverables to ask the engineer to produce
• sher link
• “Open preview link”