usedby.dev

Showcase who depends on your library with a single image embed.

usedby.dev generates beautiful, zero-config SVG images showing the top dependents of any package — perfect for your README, docs, or landing page. Supports npm, RubyGems, PyPI, Cargo, Composer, and Go.

Supported ecosystems

Quick start

Add this to your README or docs, replacing {ecosystem} and your-package with the appropriate values:

[![Used by](https://api.usedby.dev/{ecosystem}/your-package)](https://github.com/your-org/your-repo/network/dependents)

Generated with [usedby.dev](https://usedby.dev/)

That's it. No API key, no sign-up, no config.

For npm scoped packages:

[![Used by](https://api.usedby.dev/npm/@your-scope/your-package)](https://github.com/your-org/your-repo/network/dependents)

Generated with [usedby.dev](https://usedby.dev/)

Customization

Append query parameters to customize the output:

Examples

Detailed view with top 10 by stars, dark theme:

[![Used by](https://api.usedby.dev/npm/your-package?style=detailed&max=10&sort=stars&theme=dark)](https://github.com/your-org/your-repo/network/dependents)

Generated with [usedby.dev](https://usedby.dev/)

Mosaic view with 20 dependents:

[![Used by](https://api.usedby.dev/npm/your-package?max=20)](https://github.com/your-org/your-repo/network/dependents)

Generated with [usedby.dev](https://usedby.dev/)

Badge

usedby.dev also provides a Shields.io-compatible badge endpoint that displays a "used by N projects" count.

GET /:registry/:package/shield.json

Markdown:

![Used By](https://img.shields.io/endpoint?url=https://api.usedby.dev/npm/PACKAGE/shield.json)

HTML:

<img
  src="https://img.shields.io/endpoint?url=https://api.usedby.dev/npm/PACKAGE/shield.json"
  alt="Used By"
/>

Replace npm and PACKAGE with the appropriate ecosystem and package name.

See the worker README for full technical details on the endpoint.

How it works

1. Search: Queries the GitHub code search API for repositories that import your package
2. Enrich: Fetches metadata (stars, activity, archived status) for each result
3. Score: Ranks dependents using a composite score (stars * recency_multiplier) to surface active, popular projects
4. Render: Generates an SVG image with avatars and metadata
5. Cache: Serves results from Cloudflare KV with stale-while-revalidate (24h fresh, background refresh, 30-day eviction)

FAQ

Why does the first request take so long?

On a cold start, usedby.dev queries the GitHub code search API, enriches each result with repository metadata, fetches avatars, and renders the SVG. This involves many sequential API calls and can take a while due to the GitHub API limitations and rate limits. Subsequent requests are served from cache and are near-instant.

Why are some well-known dependents missing?

usedby.dev relies on GitHub's code search API, which caps results at 1,000 per query and doesn't allow to sort results by stars. For very popular packages with tens or hundreds of thousands of dependents, only a subset is discoverable, so some may be missing from the results.

How fresh is the data?

Results are cached for 24 hours. After that, the next request serves stale data while triggering a background refresh. Entries not accessed for 30 days are evicted.

Does this work with scoped npm packages?

Yes. Scoped packages like @scope/package are fully supported, just use them in the URL as-is (e.g., https://api.usedby.dev/npm/@scope/package).

Which ecosystems are supported?

npm, RubyGems, PyPI, Cargo, Composer, and Go. Use the corresponding prefix in the URL (e.g., /pypi/requests, /cargo/serde, /go/gin-gonic/gin).

Self-hosting

usedby.dev is open source. You can deploy your own instance.

Prerequisites

• Node.js >= 18
• npm 11+
• A GitHub personal access token
• A Cloudflare account

Setup

git clone https://github.com/sarahdayan/usedby.dev.git
cd usedby.dev
npm install

Create apps/worker/.dev.vars with your GitHub token:

GITHUB_TOKEN=ghp_your_token_here

Development

npm run dev

This starts:

• the worker at http://localhost:8787
• the web app at http://localhost:3000
• the SVG preview at http://localhost:5173

Testing

npm test

Deployment

• Worker — Deployed to Cloudflare Workers via npm run deploy -w apps/worker
• Web — Deployed to Vercel

Project structure

This is a Turborepo monorepo:

• apps/worker — Cloudflare Worker serving the image endpoint and data pipeline
• apps/web — Landing page (Next.js)
• apps/preview — SVG preview app for visual iteration on renderers

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

License

MIT