If you maintain an npm package — a CLI tool, a React component library, a build plugin, a utility — your weekly download count is one of the cleanest single signals visitors read as "this is widely used, I can trust it." Putting that number on your website (not just your npm page) is one of the highest-ROI 60-second additions you can make to a package landing, a docs site, a SaaS marketing page, or a portfolio.

This guide walks every option — Shields.io's badge, npm-stat.com's chart, and a one-line drop-in pill — and shows which to pick. If you're skimming: FeedPulse's free npm Downloads badge is the lightest path. No API key, no signup, supports scoped packages.

What is an npm Downloads badge?

An npm Downloads badge is a small visual element you embed on a third-party website that shows your package's download count over a fixed period (typically last day, last week, or last month), pulled live from npm's official download counter API.

npm exposes the download count through its public unmetered endpoint at https://api.npmjs.org/downloads/point/last-week/your-package. The endpoint is open, unauthenticated, and lets you query any of three windows:

• last-day — yesterday's downloads (npm reports one day behind; today's number is always pulled tomorrow)
• last-week — the past 7 days
• last-month — the past 30 days

The "last week" total is the canonical brag number — long enough to smooth daily noise, short enough to feel fresh. The other two are for specific contexts: last-day for spikes after a launch, last-month for stability narratives.

Why your website needs one

1. The credibility delta is huge

"3.2M downloads / week" beats "popular package" by an order of magnitude in conversion testing. A live download count is the single most-recognized "this is real" signal in the npm ecosystem; even seasoned developers will skim a package page in 2-3 seconds, see the number, and decide.

2. Social proof that updates itself

A static "downloaded by thousands" line on your landing page is fine, but every visitor wonders if it's current. A live badge that says "npm 3.2M / wk" collapses the doubt.

3. Native fit with other developer signals

A download count alone says "people install this." Combined with a GitHub Stars badge, it also says "people like this." Side by side, the two signals together convert significantly better than either alone. Full play in the GitHub Stars how-to.

4. SEO body content

For a thin page (a single-package marketing landing, a side-project README mirror), the badge adds visible, unique on-page content. Combined with the badge's own keyword-rich landing, the page becomes an indexable result for "npm downloads badge" queries.

Method 1: Shields.io SVG badge (the developer default)

The most-used solution. Shields.io renders an SVG badge live:

<img alt="npm downloads" src="https://img.shields.io/npm/dw/your-package">

Pros: Universal, looks at home in a README, no JS. Cons:

• Re-fetched on every page load — no client cache.
• Soft rate limit on the free tier; high-traffic pages occasionally 503.
• Locked to Shields' canonical pill style.
• No click-through behavior — you'd wrap in <a> yourself.

Best fit: READMEs, technical docs that look like docs.

Method 2: npm-stat.com chart embed

npm-stat.com renders a richer downloads chart you can iframe:

<iframe src="https://npm-stat.com/charts.html?package=your-package&from=2025-06-01&to=2026-05-30"
        width="800" height="400" frameborder="0"></iframe>

Pros: Time-series chart instead of a single number; useful for "growth story" pages. Cons:

• Big iframe (~150-300 KB).
• charts.html itself is heavy; performance impact is noticeable.
• Locked styling — no brand fit.

Best fit: an "About this package" page where you genuinely want to show the growth curve. Bad fit for a hero badge.

Method 3: Custom-built (the hard way)

npm's downloads endpoint is open:

curl https://api.npmjs.org/downloads/point/last-week/your-package

Response:

{
  "downloads": 3245678,
  "start": "2026-05-23",
  "end": "2026-05-29",
  "package": "your-package"
}

You can call this from your backend, cache it, render however. The catch: you build and maintain the visual, handle scoped packages (@scope/pkg → the slash needs URL-encoding), handle the "package doesn't exist" 404 case, handle accessibility, theming, locales.

For one website, rarely worth it. For many, it might be.

Method 4: The one-line drop-in badge (recommended)

This is what we built FeedPulse's free npm Downloads badge to be. One line of HTML, ~4 KB gzipped, picks up your package's weekly downloads live, renders a small embeddable pill with seven theme options.

<script async
  src="https://feed-pulse.com/api/embed/npm-downloads.js?package=your-package&period=last-week&theme=npm">
</script>

What you get:

• npm 3.2M / wk pill in npm's signature red (or 6 alternative themes — obsidian, ivory, indigo, emerald, slate, transparent).
• Live count cached server-side for 6 hours so your site never hammers npm's API.
• Click-through opens the package page on npm.
• Auto-formats large counts (1.2k → 3.2M → 412B if you ever make it that far).
• Lighthouse 100/100/100/100 verified on the badge's own landing page.
• Three period options: last-day, last-week (default), last-month.
• Scoped packages supported transparently — paste @scope/your-package and the slash is handled.

Open the customizer, paste your package name, pick a period + theme, copy the snippet. No account, no email.

Scoped packages

If your package is @types/node or @vercel/og (anything starting with @), paste the full slug including the @ into the customizer. The snippet handles the URL-encoding automatically:

<script async
  src="https://feed-pulse.com/api/embed/npm-downloads.js?package=%40types%2Fnode&period=last-week&theme=npm">
</script>

(The %40 and %2F are URL-encoded @ and / respectively — paste @types/node directly in the customizer and the encoding happens for you.)

Embedding on specific platforms

The snippet is plain HTML and works wherever you can paste a <script> tag.

WordPress

• Gutenberg: Custom HTML block. Paste. Done.
• Classic editor: switch to Text tab. Paste.
• Sidebar / footer: Appearance → Widgets → Custom HTML.
• Strict installs: use Code Snippets plugin.

Static-site generators (Hugo, Jekyll, Astro, Next.js, Eleventy)

Drop into your layout template before </body>.

Docusaurus / VuePress / MkDocs

Paste the snippet directly in any .md / .mdx page.

Shopify, Webflow, Ghost, Framer, Carrd

Same pattern as for the GitHub Stars badge — Custom Code block, paste, publish.

README.md

GitHub READMEs strip <script> tags, so use Shields.io's SVG badge there:

![npm downloads](https://img.shields.io/npm/dw/your-package)

Use FeedPulse on your website; use Shields.io on your README.

Which period should you display?

• last-week — default. Best signal-to-noise. Use this on every marketing surface unless you have a specific reason not to.
• last-day — only useful right after a launch when daily numbers are climbing fast. Avoid otherwise — daily counts fluctuate weekly (weekends are quieter for most dev tools) and a low number on a slow day looks bad.
• last-month — for stability narratives. "Steady 12M / month" reads stronger than a wobbly week-by-week story for established packages.

You can swap the period later just by changing the period= query parameter; you don't need to re-customize.

Performance comparison

Lighthouse mobile, fast 3G, Moto G4 emulation, against a clean 100/100/100/100 landing.

Privacy + GDPR

One server-side proxied request per (period, package) per 6-hour cache window. No cookies, no fingerprinting, no visitor IP leaks to npm. GDPR-safe by default. Full data flow in the npm Downloads FAQ.

Common issues

"The badge shows '—' instead of a number." Either the package doesn't exist, the spelling is off, or it's a scoped package whose @ got dropped. Double-check the slug matches https://www.npmjs.com/package/... exactly.

"Numbers look truncated as 3.2M." Intentional. Predictable pill width across layouts. If you absolutely need long-form numbers, file a widget idea for a format=full toggle.

"My package just went viral but the badge shows yesterday's number." npm's downloads endpoint itself is always one day behind (it's how npm aggregates). FeedPulse adds a 6-hour cache on top of that, so the badge can be up to ~30 hours behind npm's latest published figure. For 99% of "look at our weekly downloads" use cases, ~30 hours is plenty fresh.

"Scoped package isn't working." Make sure you typed the full slug with the leading @. types/node won't work; @types/node will.

What to pair with the npm Downloads badge

Downloads solo is fine, but the developer audience reads multiple signals at once. Stack with:

• Free GitHub Stars badge — the one-two combo. Conversion lifts 10-20%. Embedding guide.
• Free Discord server widget — if your package has a community / support channel. Embedding guide.
• Free YouTube live widget — if you stream development sessions or office hours.

Together: "people use it" (downloads), "people like it" (stars), "people talk about it" (Discord), "people watch it being built" (YouTube live).

Wrapping up

An npm Downloads badge is the cleanest single trust signal you can put on a developer-audience landing. Shields.io is canonical for READMEs. The FeedPulse drop-in is the fastest path to a styled, themable, performant badge on your website. Both are free; pick by surface.

If you want a live badge on your site in the next 60 seconds, open the customizer, paste your package name, copy the snippet. Done.