npm-install-size

Check the published install size of any NPM package before installing it, or the actual installed size after install with --installed.

Features

• Fetches and extracts the latest or specific version of any npm package
• Calculates and displays the total uncompressed install size
• Supports multiple packages at once
• Human-readable, JSON, CSV, and Markdown output modes
• Summarize mode: shows file count, largest file, and estimated download time
• Scoped package support (e.g. @babel/core)
• Dependency tree size with --deps
• Minified & gzipped size estimation
• Top N largest files and file type breakdown
• Compare mode for side-by-side stats
• Historical size tracking for previous versions
• Badge generation for README
• Interactive mode for easy CLI use
• Output to file in any format
• Custom download speed for time estimation
• Progress bar for multi-package checks
• Config file support (.npm-install-sizerc)
• Programmatic API for Node.js scripts
• No install required (run with npx)

Usage

Basic

npx npm-install-size react express lodash

Output:

📦 [email protected]: 167 kB
📦 [email protected]: 197 kB
📦 [email protected]: 1.41 MB

Analyze a Local Package Directory

npx npm-install-size ./packages/my-lib

Output:

📦 ./packages/[email protected]: 42 kB

Analyze a Workspace Package

npx npm-install-size --workspace my-lib

Note: Workspace support requires your root package.json to define workspaces.

Check a Specific Version

npx npm-install-size [email protected]

Output:

📦 [email protected]: 316 kB

Dependency Tree Size

npx npm-install-size express --deps

Minified & Gzipped Size

npx npm-install-size react --minified --gzipped

Top N Largest Files

npx npm-install-size react --top 5

File Type Breakdown

npx npm-install-size react --types

Compare Mode

npx npm-install-size react vue --compare

Historical Size Tracking

npx npm-install-size react --history 5

Badge Generation

npx npm-install-size react --badge

Interactive Mode

npx npm-install-size --interactive

Output to File

npx npm-install-size react --json --output result.json

Custom Download Speed

npx npm-install-size react --speed 2

Check Installed Size (node_modules)

npx npm-install-size --installed

Output:

⚠️  This is the actual installed size on disk, including all dependencies. It may be much larger than the published tarball size.
📦 node_modules: 132 MB

npx npm-install-size --installed express

Output:

⚠️  This is the actual installed size on disk, including all dependencies. It may be much larger than the published tarball size.
📦 node_modules/express: 1.2 MB

Config File Support

You can set default options in a .npm-install-sizerc file (JSON) in your project root:

{
  "packages": ["react", "express"],
  "json": true,
  "summarize": true,
  "topN": 5,
  "output": "sizes.json"
}

• CLI arguments always override config defaults.
• If you run the CLI with no arguments, the config is used.

Programmatic API

You can use npm-install-size as a library in your Node.js ESM projects:

import {
  getInstallSize,
  getDependencyTreeSize,
  getMinifiedAndGzippedSize,
  getFileTypeBreakdown
} from 'npm-install-size';

const info = await getInstallSize('react');
console.log(info);

const tree = await getDependencyTreeSize('react');
console.log(tree);

const minified = await getMinifiedAndGzippedSize('react');
console.log(minified);

const types = await getFileTypeBreakdown('react');
console.log(types);

Options

• Pass one or more package names (optionally with versions, e.g. [email protected])
• --json — Output results as JSON
• --csv — Output results as CSV
• --md — Output results as Markdown table
• --summarize — Show file count, largest file, and download time
• --deps — Show total size including all dependencies
• --minified — Estimate minified size
• --gzipped — Estimate gzipped size
• --top N — Show top N largest files
• --types — Show file type breakdown
• --compare — Compare multiple packages side-by-side
• --history N — Show install size for last N versions
• --badge — Output a Markdown badge for README
• --interactive — Use interactive prompts
• --output <file> — Write output to a file
• --speed <mbps> — Set custom download speed for time estimation
• --installed — Show the actual installed size of node_modules or a specific package (includes all dependencies; may be much larger than the published tarball size)

FAQ

Q: Does it support monorepos or workspaces? A: Yes! You can analyze local package directories or workspace packages. Use a local path (e.g. ./packages/foo) or --workspace <name>. Dependency tree analysis (--deps) is only supported for published packages.

License

MIT