Hoe je een npm downloads badge op je website inbedt

Stap voor stap: toon de wekelijkse downloads van je npm-pakket op elke website met één regel HTML, geen API-sleutel, inclusief scope-pakketten en styling.

You can embed an npm downloads badge on any website to show how often your package is installed.

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 first things many developers look at when judging whether a package is actively used. Putting that number on your website (not just your npm page) is a quick addition to a package landing page, a docs site, a product 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: Shields.io is the standard for READMEs, and for a styled badge on a website FeedPulse's free npm Downloads badge needs no API key or signup and 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 a public endpoint at https://api.npmjs.org/downloads/point/last-week/your-package. The endpoint needs no authentication 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 most common choice — 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 embed an npm downloads badge on your website

1. It's a number developers already look for

A weekly download count is one of the first things many developers check on a package page. Showing it on your site puts that context where visitors are deciding, instead of making them go to npm to find it.

2. It stays current on its own

A static "downloaded by thousands" line goes stale, and visitors can't tell when it was written. A live badge that reads "npm 3.2M / wk" shows the current figure every time.

3. It pairs well with other developer signals

A download count says "people install this." Next to a GitHub Stars badge, it also says "people bookmark this." Full walkthrough in the GitHub Stars how-to.

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:

  • Fixed to Shields' pill style (you can change the colour and label with query parameters).
  • No click-through by default — wrap it in an <a> yourself.
  • It's an image, so screen readers only get the alt text you write.

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

Method 2: link to an npm-stat.com chart

npm-stat.com draws a downloads chart for any package over a date range you choose. It isn't an embeddable widget, but it works well as a link from an "About" or "Stats" page:

<a href="https://npm-stat.com/charts.html?package=your-package">Download history on npm-stat</a>

Pros: A time-series chart instead of a single number; useful when you want to show growth. Cons: It's a separate site, so visitors leave your page, and you can't style it.

Best fit: a stats or "About this package" page. Not a replacement for a 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, about 3.5 KB of gzipped JavaScript, 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).
  • Benchmarked on the badge's own landing page — run PageSpeed Insights on it yourself rather than taking a screenshot of my scores on trust.
  • 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

Any third-party embed adds some weight. An SVG image like Shields.io's is one small request with no JavaScript. A script-based badge like FeedPulse's adds a small async script (about 3.5 KB gzipped) plus one API request. Rather than trusting anyone's table, measure on your own page: run PageSpeed Insights before and after adding a badge.

Privacy

The badge script calls FeedPulse's API, which fetches the count from npm server-side and caches each package and period for 6 hours, so your visitors' browsers never contact npm directly. The badge sets no cookies. Like any embedded script, loading it does mean each visitor's browser makes a request to feed-pulse.com. More detail 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 most "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:

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 a simple, honest signal to put on a developer-facing page. Shields.io is canonical for READMEs. The FeedPulse drop-in gives you a styled, themeable 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.

FeedPulse - Featured on Startup Fame Fazier badge