Bundlephobia: a size number that comes from building your package

The figure comes out of a build service, not a lookup table

The manifest splits the work into build-service, cache-service, jvm-package-build-stats, scripts, and packages/*, while the root package.json points main at index.ts, is marked private, and carries version 1.0.1 with the description Find the cost of adding new frontend dependencies. The top level entry list puts client, server, pages, and next.config.js side by side, so the page you read and the code that produces the number are separate pieces of the same repository. The practical consequence is that the size on bundlephobia.com is the output of a build run by the service, rather than a figure you can inspect and recompute from a published table.

MissingDependencyError is a statement about the package's metadata

This is the failure the project explains best. MissingDependencyError is thrown when a package requires a dependency without adding it to its dependencies or peerDependencies list. With no such declaration the size cannot be reported reliably, because there is nothing to resolve against, so the tool refuses rather than guessing at a number. The fix does not sit on your side: the documented route is to report an issue with the package author and ask for the missing package to be added to its package.json. For someone comparing two libraries, that means a refused answer tells you the maintainers left a dependency undeclared, which is worth knowing before you take the package, and not much of a verdict on its weight.

BuildError hands you a stack trace and an issue link

The second failure is the less generous one. The documented procedure is to open the devtools console, read the detailed stack trace, and open an issue on the repository with the relevant details, and the README adds that a more ideal solution is still to come. So a BuildError is a dead end for an automated check. The README documents no error code to match on and no way to separate a package that cannot be built from a transient failure inside the build service. You are expected to investigate it yourself and hand the details to the maintainers, which is a fine arrangement for an open source project and a poor one for a build pipeline that needs a decision either way.

The beta marker sits on exactly the measurement you might trust least

The feature list is four lines: it works with ES6 packages, it can build css and scss packages as well (beta), it reports historical trends, and it shows package composition. The beta marker deserves the most attention, because a stylesheet package is exactly where a size number tempts you to skip verification, and that number comes from the part of the pipeline the project itself flags as unfinished. The other two features are what turn a single figure into a decision. A trend line shows whether a dependency has been growing over time, and the composition view shows which files inside it carry the weight, so you can see whether you are paying for one large file or many small ones. Neither changes the underlying build; they are views onto its result.

The default branch is bundlephobia, so main and master resolve to nothing

The repository does not use main or master, and the Contributing link follows that choice, pointing at /blob/bundlephobia/CONTRIBUTING.md. That is a small detail that breaks automation in a confusing way: a script, a clone step, or a badge URL that appends main to the repository address gets nothing back, and a new contributor who assumes main will hunt for a branch that was never there. The entry list also includes .env.defaults while the server dependencies carry dotenv at ^8.6.0 and dotenv-defaults at ^2.0.2, so configuration appears to come from environment defaults, which is worth knowing before you try to point a local copy of this at anything.

Tagged releases stopped in 2019 while pushes kept arriving

The newest releases are v1.2.1 from 29 Sep 2019, v1.2.0 from 17 Sep 2019, and v1.1.0 from 26 Aug to 2nd Sept 2019, and all three carry a publication timestamp of 2019-10-29. The repository is not archived and its last push is dated 2026-10-27, so the code keeps moving while tagged releases have not been cut in years. The root package.json still reads version 1.0.1, below the newest tag, so the manifest version is not a dependable marker either. What follows from that: do not treat any bundlephobia version as an API contract. The Support section invites you to build on the API and get in touch, and it names no version, no changelog, and no compatibility promise.

Node 24 engines, a yarn lockfile, and four competing CI signals

Read the toolchain files together and they disagree in an instructive way. engines asks for node >= 24.0.0 and npm >= 5.4.x in the same breath, and the repository ships yarn.lock with .yarnrc.yml alongside the workspace list, which makes it a yarn workspace install rather than an npm one. Sitting next to those are .travis.yml, jest.config.js, playwright.config.ts, an e2e directory, and a test-packages directory, so several testing and CI conventions are present at once. The linting setup is newer still, with .oxlintrc.json and .oxfmtrc.json, renovate.json covers dependency updates, and process.yml suggests a process manager for running the services. Anyone forking this should pick a runner deliberately instead of inferring one from the file listing.

Badges and six integrations all point at the same hosted site

The only code in the README is the badge recipe, two lines that point at badge services and show an example size for react:

- [badgen.net](https://badgen.net/#bundlephobia) - example size of react:
- [shields.io](https://shields.io/#/examples/size) - example size of react:

Those two are the documented embedding. Nearby, the project names what other people built on it: size shown in the browser on package searches at yarnpkg.com, bundlephobia-cli as a command line client, importcost as an Atom plugin, a JS Bundle Size extension for Chrome and Firefox that adds package size to GitHub and npm pages, stats at the top of npmcharts.com, and Rollpkg as a build tool. Every one of those routes ends at the hosted site, so a single unreachable bundlephobia.com quiets all of them at the same moment. Nothing in the README describes a badge refresh interval, an offline mode, or a fallback figure.

Editorial conclusion

Bundlephobia earns its place as a quick pre-install check on a single dependency, and its two documented error states tell you more about the package under test than about the tool. It is a hosted service first and a repository second: no release has been cut since v1.2.1 in 2019, package.json is private at 1.0.1, and the self-hosted path has no documented command. If you plan to call it from CI, decide in advance what your pipeline does when bundlephobia.com does not answer, and treat MissingDependencyError and BuildError as reports to file upstream rather than numbers to wait on.

Frequently asked questions

Official sources

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