Bundlephobia: Know the Bundle Size Cost of an npm Package Before Installing

The Cost Bundlephobia Measures: Why Package Size Matters Before Install

Every npm package added to a frontend application increases the JavaScript payload the browser must download, parse, and execute. Not all packages have the same cost. A utility library with a broad API surface may add tens of kilobytes; a focused single-purpose module may add less than one. The problem is that npm does not publish this information: the package size on the registry is the unprocessed source, not the minified and gzipped bundle a browser actually receives.

Bundlephobia fills this gap. It takes a package name and version, builds the package in isolation using a bundler, and reports the minified size and the gzipped size. These are the numbers that correspond to what a browser actually downloads when the package is included in a production bundle. The README describes this as knowing the performance impact of including an npm package in an app's bundle.

The service is available at bundlephobia.com. No account or install is required. Entering a package name on the site's search field returns size information within a few seconds for packages that have already been cached.

How Bundlephobia Builds and Reports Package Metrics

Bundlephobia builds each package in a controlled environment and measures the output. The README describes the features that come out of this process: ES6 package support, CSS and SCSS package support (marked as beta in the README), historical size trend data, and a package composition view.

Historical trends show how a package's bundle size has changed across published versions. This is useful for identifying regressions: if a package doubled in size between two minor versions, the trend view makes that visible. The package composition view breaks down which dependencies within the package contribute to its total size.

The codebase is a Next.js TypeScript application. The package.json lists esbuild as the bundler used internally for building packages under analysis. A build-service workspace handles the package build logic, and a cache-service workspace handles caching results. The Node.js engine requirement in package.json is version 24 or later.

Bundlephobia also powers badge integrations. The README notes that badgen.net and shields.io both include Bundlephobia data, so maintainers can embed a size badge in their own README files without running any build.

Using Bundlephobia: Web Interface, API, and Community Integrations

The primary interface is the web service at bundlephobia.com. Searching for a package name returns the current version's size along with the historical trend chart and the dependency tree breakdown. Visiting the site requires no authentication and no local tooling.

The README lists several integrations built on the Bundlephobia API: yarn's package search at yarnpkg.com shows bundle size data for packages in search results. A command-line client named bundlephobia-cli is available separately. An Atom editor plugin called importcost shows the size of imported packages inline in the editor. A cross-browser extension for Chrome and Firefox called JS Bundle Size adds package size information to GitHub and npm pages.

For CI and documentation, the badge integrations allow embedding a current size value in a repository README. The badgen.net and shields.io services each have documented badge types for Bundlephobia, returning the package's minified and gzipped size as a formatted badge image.

Bundlephobia's package.json includes @modelcontextprotocol/sdk, which means the codebase supports the Model Context Protocol. This allows AI tools that support MCP to query Bundlephobia data programmatically.

Error Cases: MissingDependencyError and BuildError

Bundlephobia's README documents two specific errors that users will encounter when a package cannot be measured.

MissingDependencyError means the package requires another package at runtime but does not declare it in its dependencies or peerDependencies list in package.json. Without that declaration, Bundlephobia cannot reliably resolve and bundle the dependency, so it refuses to report a size. The README advises reporting the issue to the package author and asking them to add the missing dependency to their package.json.

BuildError means the package failed to build entirely. The README notes that a detailed stack trace is available in the browser's developer tools console, and users are directed to file a GitHub issue with the relevant details.

Both errors reflect a real limitation: Bundlephobia measures packages by building them, and packages that are poorly structured or that have undeclared dependencies will fail. The reported size for packages that do build successfully is a measurement of the package in isolation, not of the package as it would be bundled in a specific application with tree-shaking applied.

Where Bundlephobia Falls Short: Application-Level Bundle Analysis

Bundlephobia measures a package in isolation. It does not measure how a package behaves inside an application with dead code elimination, shared module deduplication, or code-splitting configured. If an application already imports React, adding a package that also uses React does not increase the bundle size by that package's full reported number, because React is already present. Tree-shaking may also eliminate large portions of a package if only a small subset of its exports are used.

For this reason, Bundlephobia cannot replace an analysis of the application's actual built output. Packages that are larger than expected after build optimization analysis include the full scope of what Bundlephobia reports, minus whatever the bundler eliminated, minus whatever was already present as a shared dependency.

There is also no local install option for developers who want to run their own instance. Bundlephobia is a web service with a self-hosted codebase, but the README does not provide self-hosting instructions.

Bundlephobia vs webpack-bundle-analyzer: Pre-install vs Post-build

webpack-bundle-analyzer is a tool that visualizes the composition of a webpack build output. It runs after the build and displays a treemap showing which modules and dependencies take up space in the final bundle. It works on the application's actual output, with tree-shaking and code-splitting applied.

Bundlephobia operates before a package is installed. It answers whether a package is worth adding to a project without requiring any local build. These two tools address different questions. Bundlephobia answers "how large is this package on its own?" webpack-bundle-analyzer answers "where is my application bundle's size actually going?"

For Vite-based projects, vite-bundle-visualizer provides a similar post-build analysis to webpack-bundle-analyzer. None of these local analysis tools replace the pre-install convenience of Bundlephobia for evaluating a candidate package before committing to it.

Editorial conclusion

Bundlephobia is the right tool when you want a quick, no-setup answer to the question of how much a specific npm package will add to a production bundle. It is not a substitute for analyzing your own application's bundle after tree-shaking and code-splitting, since the size Bundlephobia reports is for the package in isolation. For that, webpack-bundle-analyzer or vite-bundle-visualizer run against your actual build output. Bundlephobia's GitHub repository notes it is looking for contributors and co-maintainers in issue #683, so teams that depend on it should factor that into any long-term planning.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes