# Package Phobia: asking what an npm dependency costs before you install it

> A web service that measures the install size of an npm package and remembers it over time, plus a JSON API and a README badge. Here is what it measures and what it does not.

**styfle/packagephobia** — ⚖️ Find the cost of adding a new dependency to your project

- Repository: https://github.com/styfle/packagephobia
- Website: https://packagephobia.com
- Stars: 2,315 · Forks: 63
- Language: TypeScript
- License: MIT
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/styfle-packagephobia

## The question it answers is narrower than most size tools

Package Phobia reports the size of an npm package before you install it, and keeps a record of that size over time. The stated purpose is to inspect a candidate dependency without spending disk space or waiting on an install.

That framing is narrower than the more familiar category of bundle analysis, and the README is explicit about it. Its purpose is to find the cost of adding a dependency to a project, which is a question about the package as distributed rather than about the code that ends up in your output. A library that ships forty megabytes of fixtures you never import is expensive to install and cheap to bundle. Package Phobia measures the first of those facts.

The caching model is worth understanding because it explains the user experience. Results are saved, so the first person to ask about a package waits a little while for the measurement to be produced, and everyone after that gets an immediate answer. In practice that means a cold package is slow and a known package is instant, which is the reverse of what a first-time visitor might expect.

The demo is built around comparisons rather than single lookups, and the README suggests categories where the decision is genuinely close: test harnesses, web frameworks, JavaScript bundlers, task runners, HTTP request libraries, glob implementations, argument parsers, site generators, type checkers, linters, color formatters, command line interfaces, desktop frameworks, headless browsers and package managers. That list is a good argument for the tool's existence, since in each of those categories two credible options exist and their sizes often differ by an order of magnitude.

The site is at packagephobia.com, and GitHub records the same URL as the project's homepage.

## Where it sits among a crowded field of size tools

The README contains one of the more complete comparisons in this part of the ecosystem, and it is the section to read before deciding which tool you need. Package Phobia is described as a web app that reports the install size of a package over time. Bundle Phobia, a project it lists as prior art, reports the size after webpack bundles the package over time. Those are different measurements of different things.

The rest of the list covers bundler-based and CLI approaches. Bundle.js and Pkg-Size bundle a custom snippet or one or more packages with esbuild. Cost Of Modules and npm Size are command line tools that report on packages you have already installed. Badge Size gives the gzip size of a single file as an SVG badge. Size Limit and Bundle Size are command line tools that fail a build when size crosses a limit, which makes them CI tools rather than research tools. Import Cost is an editor extension. Build Size is a GitHub app that comments on a pull request with artifact sizes.

Two entries in that list are called out as prior art: Bundle Phobia and Cost Of Modules. Naming the inspiration is useful context, because the question a reader actually has is often whether they need Package Phobia at all, or whether Bundle Phobia already covers their case.

The practical division of labour is straightforward. If the question is what adding this line to package.json costs you in download and disk, this is the tool. If the question is what your bundle weighs after tree shaking and minification, you need a bundler-based analyser instead. Using the wrong one produces a number that feels authoritative and answers nothing.

Package Phobia also offers a badge or shield for a README, and a JSON API so other tools can fetch the size. Both are listed among its features, alongside the historical size chart.

## A Node service that installs packages to measure them

The manifest tells you what the service is built from. The runtime dependencies are a React front end, the npm client library itself, an LRU cache, a Redis client, semver and badgen for badge generation:

```json
  "dependencies": {
    "badgen": "^3.2.3",
    "ioredis": "^5.10.0",
    "lru-cache": "^11.2.6",
    "npm": "^11.19.1",
    "react": "^18.3.0",
    "react-dom": "^18.3.0",
    "semver": "^7.7.4"
  }
```

Depending on `npm` as a library is the expected way to measure an install: the service resolves a package version and asks the client for what that version would bring down. `ioredis` alongside `lru-cache` maps exactly onto the caching behaviour the README describes, with Redis for shared storage across instances and the LRU cache in front of it.

The engine requirement is unusually narrow, pinned to a single major version:

```json
  "engines": {
    "node": "24.x"
  }
```

That is a deliberate choice for a hosted service rather than a library, since nothing consumes this as a dependency, and the package is marked private. The TypeScript toolchain is current: TypeScript 6, ESLint and Prettier with a pre-commit hook that runs the formatter and stages the result. The lockfile and `vercel.json` in the tree indicate a deployment on Vercel.

The test script is unusual enough to be worth quoting, because it explains a directory named `hardlink` in the tree:

```bash
tsc && rm -f test/hardlink/link && node --test ./dist/test/**/*.test.js
```

The full script creates a hard link from an original test file before running the node test runner over the compiled output. That is a test of hardlink handling, wired into the general test command rather than living in a separate suite.

## The API is real but the gatekeeping is deliberate

There is a JSON API, and the README handles it in an unusual way. Rather than publishing a key or an endpoint list, it asks that anyone who wants to use the API in a project open a pull request modifying the API Users section of API.md.

That is a deliberate choice for a free service with no stated funding model. It means the maintainer knows who is depending on it, which is the difference between an API that breaks in a refactor and one that does not. It also means there is no self-service path, so if you want to automate size checks across a large dependency list, budget for the conversation.

API.md is present in the repository tree, so the details of the endpoints and usage are there even though the README defers to it entirely.

The README also lists where the project has been written about, which is a reasonable proxy for how visible the service is: the AWS Developer Tools Blog, an npm weekly, a ponyfoo weekly, a habr company blog, a podcast, a conference talk, the changelog newsletter, and various social posts. The AWS post is the substantive one, on halving the publish size of the modular AWS SDK for JavaScript clients, which is exactly the kind of decision this tool is meant to inform.

## Project state and the limits of what it can tell you

The repository has 2,313 stars and 62 forks, with 12 open issues. The last push was 2026-09-20, so it is being worked on. The license is MIT. The GitHub releases list is empty, which for a continuously deployed web service is unremarkable: there is no library to version, since the npm package is private and marked as such.

What the service cannot tell you is worth being clear about. It measures what npm would install for a version of a package, which is not the same as what a bundler would include from it, and not the same as what ends up in a deployed artifact. It also cannot see your context: the same package costs a different amount depending on whether you use one function, a whole entry point, or the package as a build-time tool.

The number it does report is still useful precisely because it is unambiguous. A 20 megabyte install is 20 megabytes of download, disk and cold cache, whatever your bundler later does with it. For a team reviewing a dependency addition, that is a concrete number to argue about rather than an estimate.

One small detail in the project itself is easy to miss and mildly amusing: the service depends on npm as a library to measure other npm packages. It is not a criticism, just the shape of the problem.

## Where the README stops and the service takes over

The README settles three things: what the number means, how it differs from a dozen alternatives, and that results are cached after the first request. It does not document the measurement method, the API surface or the operational limits, and those all live elsewhere.

That division makes sense for a hosted service where the README's job is to explain the concept. It also means a reader evaluating the service has to decide whether the distinction from bundler tools is clear enough from the prose. The comparison section does most of that work, and it is more complete on this project than the equivalent section on several competing services.

The repository itself is worth a look if you want to understand the caching architecture, because the dependency list is a compact description of it: npm for measurement, Redis for shared results, an LRU cache in front for hot packages, React for the page, badgen for the badge. There is an `api/` directory, a `src/` directory, a `public/` directory for static assets and a `test/` directory containing the hardlink fixture the test script references.

For a reader deciding whether to install it, the API requirement is the part to check first. If you want a badge in your README, it is a two-minute job. If you want to gate a large dependency list in CI, you should read API.md and be prepared to open a pull request before you can automate anything.

## Conclusion

Package Phobia is at its best as a pre-commitment check rather than a measurement tool, because install size is the number a developer can act on in the ten seconds before adding a dependency. The distinction from bundler analysis is the whole point: a dependency that installs 20 megabytes may contribute nothing to your bundle if you use one function from it, which is why the README's own comparison table exists. Read the section on how it differs from the alternatives before assuming you need both tools, and use the API rather than scraping results, since the README asks API users to add themselves to a list in API.md. The npm dependency in the project's own manifest is the one design choice worth understanding before you rely on it.

## FAQ

### What does Package Phobia measure?

It measures the install size of an npm package, meaning what npm would download and write to disk for that version, and records that size over time. That is different from bundler analysis, which measures what ends up in a bundle after tree shaking and minification.

### How is Package Phobia different from Bundle Phobia?

Package Phobia reports install size, the cost of adding the dependency at all. Bundle Phobia reports size after webpack bundles the package, which reflects what your application actually ships. The README lists Bundle Phobia as prior art and includes both in its comparison table.

### Can I use Package Phobia from a script or CI pipeline?

There is a JSON API, and API.md documents the usage details. The README asks that you create a pull request modifying the API Users section of API.md before relying on it in a project, so access is granted by the maintainer rather than by signing up.

### Why does Package Phobia take a while the first time I check a package?

Because results are cached. The first request for a package has to run the measurement and save it, while everyone after that reads the stored result and gets an immediate answer. So a package nobody has checked before is slow, and a popular one is instant.

### Is Package Phobia open source?

The repository is MIT licensed and its source is public. The hosted service is the part that is operated rather than self-hosted, and it is marked as a private package with no published releases, since it is a web service rather than a library.

## Sources

- [Issues](https://github.com/styfle/packagephobia/issues)
- [License: MIT](https://github.com/styfle/packagephobia/blob/main/LICENSE)
- [Project website](https://packagephobia.com)
- [README](https://github.com/styfle/packagephobia/blob/main/README.md)
- [styfle/packagephobia on GitHub](https://github.com/styfle/packagephobia)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/styfle-packagephobia