Widget de descargas de NPM: 5 maneras de mostrar conteos de instalación de paquetes (2026)

An npm downloads widget displays live install counts for a public npm package on a website or README. It's the single strongest social-proof element a JavaScript library can put on its landing page — "1.2M weekly downloads" closes more trial-to-adoption decisions than a dozen testimonials.

This guide compares the five most common ways to embed an npm downloads widget in 2026. If you want a themable, no-signup option for a landing page, the free npm downloads badge customizer is the fastest path.

What an npm downloads widget actually displays

The data source for every npm downloads widget — regardless of which renderer you use — is the same npm registry public download stats API. The differences are entirely in how the data is presented:

• Period: weekly, monthly, or all-time downloads.
• Format: compact (1.2M) or precise (1,234,567).
• Visual: small inline pill, hero badge, full chart with time-series.
• Update frequency: real-time vs cached at 1h / 12h / daily.

The 5 npm downloads widget options in 2026

1. Shields.io npm downloads badge

The default markdown-friendly option. Renders as an SVG image suitable for READMEs.

![NPM downloads](https://img.shields.io/npm/dw/PACKAGE_NAME?style=for-the-badge)

• Periods supported: weekly (dw), monthly (dm), yearly (dy), all-time (dt).
• Customization: color, style preset, label.
• Best for: GitHub READMEs, documentation pages.
• Limitation: Static SVG. No live update without page reload. No theming beyond color.

2. FeedPulse npm downloads widget

A modern script-tag widget designed for website embedding with full theming.

<script async src="https://feed-pulse.com/api/npm_downloads?pkg=PACKAGE_NAME"></script>

• Periods supported: weekly, monthly, total. Configurable via period param.
• Customization: 5 themes + custom hex colors + width + format (compact vs full).
• Best for: Marketing landing pages, package portfolios, documentation hero sections.
• Customizer: /free-npm-downloads-badge.

3. npm-stat.com embed

Shows a time-series chart of downloads over weeks/months/years.

![Downloads over time](https://npm-stat.com/charts.html?package=PACKAGE_NAME&from=2025-01-01&to=2026-06-01)

• Best for: Showing growth momentum (downloads chart trending up) for marketing materials.
• Limitation: Less suitable for inline use; more "embed an iframe with a chart in it."

4. Custom HTML + npm API fetch

Fetch https://api.npmjs.org/downloads/point/last-week/PACKAGE_NAME directly.

fetch('https://api.npmjs.org/downloads/point/last-week/PACKAGE_NAME')
  .then(r => r.json())
  .then(d => {
    document.getElementById('count').textContent =
      `${d.downloads.toLocaleString()} weekly`;
  });

• Best for: Teams who want pixel-perfect custom presentation.
• Limitation: Requires frontend work. Doesn't cache; high-traffic pages can hit npm's API quickly.

5. Platform plugins (Docusaurus, MkDocs, Hashnode)

Most docs platforms have native "show npm downloads" components.

• Best for: Quick embed within those platforms' visual editors.
• Limitation: Platform-locked. Doesn't transfer to other surfaces.

Quick comparison table

When to use which npm downloads widget

• README on GitHub: Shields.io. It's the canonical solution.
• Marketing landing page: FeedPulse widget. Themable, web-friendly.
• Showing growth over time in a blog post / fundraising deck: npm-stat chart.
• Custom-designed page with strict brand requirements: DIY API fetch.
• Inside Docusaurus / MkDocs: Whichever native component the platform provides.

How an npm downloads widget impacts conversion

We've seen the same pattern on multiple package landing pages: adding a visible downloads count above the fold improves the install-from-landing rate by 8-15%. The mechanism is straightforward: download counts answer "is this real and being used?" before the visitor even has to ask.

A few honest caveats:

• The effect is biggest for unknown packages. A 12k-weekly count helps a small package more than a 12M-weekly count helps a household-name package.
• The effect plateaus. Going from "no badge" to "any badge" is a step change. Going from one badge to two doesn't compound much.
• Downloads alone aren't enough. Pair with GitHub stars (people-liked-it signal) and Discord members (people-talk-about-it signal) for a complete proof set.

Common mistakes when adding an npm downloads widget

• Choosing weekly when monthly tells a better story. If your package has a small but loyal user base, monthly counts often look more impressive than weekly. Same data, better framing.
• Showing total downloads for a 6-year-old package. The number is impressive but not actionable. "Weekly downloads" signals "still being used"; "all-time" can suggest "old."
• Forgetting to enable the badge after the first release. npm download counts take 24-48h after first publish to appear. Don't add the badge on publish day — it'll show 0 and look broken.
• Embedding without a fallback. If npm's API is briefly slow, your widget should show "loading…" not blank. Always test the slow-network behavior.
• Hardcoding the count. Same mistake as with GitHub stars: any number you hardcode gets stale. Use a live widget.

Frequently asked questions

How often does an npm downloads widget update?

Cached services like shields.io and FeedPulse refresh every 1-12 hours. Direct API calls update in real time but you'll hit rate limits at scale. For most use cases, hourly refresh is more than fresh enough — npm aggregates downloads daily, not minute-by-minute.

Why does my npm downloads widget show 0?

Three common causes: (1) the package was published less than 24-48 hours ago (npm hasn't aggregated stats yet), (2) the package name is misspelled in the badge URL, or (3) the package is unpublished or private (only public packages return data).

Can I show npm downloads for a scoped package (e.g., @vue/cli)?

Yes — URL-encode the / as %2F. So @vue/cli becomes @vue%2Fcli in the badge URL. FeedPulse and shields.io both handle scoped packages correctly.

What period is best to display: weekly, monthly, or total?

Weekly is the strongest "active right now" signal for packages with steady usage. Monthly is a smoother number that doesn't fluctuate with weekend dips. Total is fine for established packages but can suggest "old" for newer ones. Most landing pages use weekly; most READMEs use weekly or monthly.

Is there a way to show npm downloads + GitHub stars together?

Yes — embed both widgets side by side. The combination is a complete social-proof signal: downloads = "people install it," stars = "people like it." Pair with GitHub stars badge for the full set.

Will an npm downloads widget slow my page?

Modern drop-in widgets are <2KB and load async. Lighthouse impact is essentially zero. Custom direct-API fetches can hurt perf if awaited inline — always make these calls non-blocking.

Embed a live npm downloads widget

If you want a themable, live npm downloads count on your package's website or documentation, open feed-pulse.com/free-npm-downloads-badge, enter your package name, pick a theme, and copy the snippet. For a complete open-source social-proof set, pair with the GitHub stars badge and Discord members widget.