Real-world API usage stats for library maintainers

Dev toolWeb1 weekNext.jsGitHub APIPostgres

The idea

Before every major version, library maintainers make breaking-change decisions with data that says nothing: npm downloads count installs, not usage, and GitHub issues represent whoever complains loudest. Whether removing that deprecated function breaks half the ecosystem or nobody at all is pure guesswork, so deprecated APIs live forever and majors ship scared.

The data exists in public code and nothing off the shelf assembles it. The wedge is per-symbol truth: search GitHub for imports of your package, AST-parse the hits, and rank your exports by real call-site counts with links to actual repos. Argument-shape sampling sharpens it further, discovering that nobody passes the options object you want to redesign turns a scary change into a safe one.

Who pays

The buyer is a devtools company maintaining an SDK or a sponsored maintainer of a serious OSS package, buying in the run-up to a major version, at 29 to 99 dollars a month; one avoided ecosystem-breaking mistake dwarfs a year of the price. Distribution: maintainer circles, RFC threads where the markdown export gets pasted (built-in visibility), and content around well-known breaking-change fiascos.

MVP scope

  • GitHub code search ingestion for npm package imports with fork/vendor/tutorial filtering
  • Babel AST parsing resolving imported symbols, aliases and call-site counts
  • Per-symbol report ranked by repos, files and call sites, with linked real examples
  • Argument-shape samples (arity, option keys) per symbol and a zero-usage exports list
  • Markdown export for RFCs; progressive results under GitHub rate limits
  • Skip for v1: Python/Go/Rust registries, private-repo org scanning, historical trend tracking, automated codemod generation, dependents-graph crawling beyond code search
// Build prompt — paste into Cursor / Claude Code / Lovable / Bolt
Build APICensus, a tool that shows library maintainers how their package is actually used across public GitHub. Stack: Next.js, GitHub API (code search plus raw content fetch), Postgres for scan results and caching; Stripe for billing.

Core flow: maintainer signs in with GitHub, enters a package name (npm first) and the symbols they are considering changing, or requests a full-surface scan. A background job queries GitHub code search for import/require statements of the package, filters obvious noise (forks, vendored node_modules, lockfiles, tutorial repos below a star threshold, dedupe by repo), fetches matching files, and AST-parses them with Babel to resolve which exported symbols each file imports and how many times each is called, including renamed imports and member-access usage on default imports. Store per-symbol aggregates: distinct repos, distinct files, total call sites, plus argument-shape samples (arity, option keys used) since knowing nobody passes the third argument is exactly what makes a breaking change safe.

Report page per scan: exported symbols ranked by real-world call-site count, each expandable to linked examples in real repos (file and line), an unused list of exports with zero public hits, and an export to markdown for pasting into an RFC or changelog discussion.

Pages: landing aimed at the week-before-a-major-version moment, scan setup, report, scan history, billing.

Implementation notes: GitHub code search rate limits are the constraint; queue aggressively, cache fetched files by content SHA, and show progressive results as the scan streams in rather than blocking on completion.

Pricing: free for one small scan; 29 GBP/month for maintainers; 99 GBP/month for orgs with private-dependents scanning via a read-only App install.

// More Dev tool ideas