Calculate the size of your npm package distribution
Command-line tool to:
- Analyze the publish size of your npm package (what gets uploaded to npm)
- Measure the install size of any npm packages (including all dependencies)
- Analyze your existing
node_modulesdirectory
Support this project by ⭐️ starring and sharing it. Follow me to see what other cool projects I'm working on! ❤️
Curious how big your package is when published?
Analyze what will be published to npm:
pkg-size publish # current directory
pkg-size publish ./package/path # specific pathOrder files by name:
pkg-size publish --sort-by=nameShow compressed sizes:
pkg-size publish --size=gzip # gzip compression
pkg-size publish --size=brotli # brotli compressionMeasure the install size of npm packages including all transitive dependencies.
Packages are installed in a temporary directory.
Measure install size:
pkg-size install lodash # single package
pkg-size install lodash @babel/core typescript # multiple packagesSort by:
pkg-size install lodash --sort-by=name # by name ascending
pkg-size install lodash --sort-by=size:desc,name:asc # by size desc, then name ascGroup by:
pkg-size install @babel/core --group-by=scope # by npm scope (@babel, @types, etc.)
pkg-size install lodash react --group-by=license # by license type
pkg-size install lodash react --group-by=author # by package author
pkg-size install lodash react --group-by=level # by dependency depth (0=direct, 1=transitive, etc.)Analyze an existing node_modules directory.
pkg-size analyze # current directory
pkg-size analyze ./path/to/project # specific pathSupports the same --sort-by and --group-by options as the install command.
Display help message
Display version number
JSON output
Size type to display. Options: raw, gzip, or brotli. (default: raw)
Sort list by name or size (default: size)
Glob to ignore files from list. Total size will still include them.
Sort by one or more properties with optional direction. Format: property:direction (comma-separated).
Properties: name, version, size, license, author, dependencySize, dependencyCount
Directions: asc (ascending), desc (descending). Default direction is asc when omitted.
Default: size:desc,name:asc
Examples:
--sort-by=name- sort by name ascending--sort-by=size:desc- sort by size descending--sort-by=size:desc,name:asc- sort by size desc, then name asc for ties
Group packages by scope, license, author, or level. Scoped packages (e.g., @babel/core) are grouped under their organization. License and author information is extracted from package.json. Level groups by dependency depth (0 = direct dependency, 1 = transitive, etc.).
How --group-by and --sort-by interact:
- If
--sort-bystarts withsize, groups are sorted by their total size - Otherwise, groups are sorted alphabetically by group name
- Packages within each group are always sorted by the full
--sort-bycriteria
--group-by=author --sort-by=size:desc # Groups by total size, packages by size
--group-by=license --sort-by=name # Groups alphabetically, packages by nameSupports the same options as analyze, plus:
Package manager to use. Options: npm, pnpm, yarn. Auto-detected from npm_config_user_agent by default.
Analyze the publish size of a local package:
import { getPackageSize } from 'pkg-size'
// Get the package size of the current working directory
const result = await getPackageSize(process.cwd())
// With options
const resultWithOptions = await getPackageSize('/path/to/package', {
sizes: ['size', 'gzip', 'brotli'],
ignoreFiles: '*.map'
})type FileEntry = {
path: string
size: number
sizeGzip: number
sizeBrotli: number
}
type PackageSizeResult = {
packagePath: string
tarballSize: number
files: FileEntry[]
privatePackage: boolean
}
type PackageSizeOptions = {
// default: ['size', 'gzip']
sizes?: ('size' | 'gzip' | 'brotli')[]
ignoreFiles?: string
}
function getPackageSize(
packagePath: string,
options?: PackageSizeOptions
): Promise<PackageSizeResult>Measure the install size of npm packages (including all dependencies):
import { getInstallSize } from 'pkg-size'
// Single package
const result = await getInstallSize(['lodash'])
// Multiple packages
const multiResult = await getInstallSize(['lodash', 'react', '@babel/core'])
// Also accepts space-delimited string
const stringResult = await getInstallSize('lodash react')type PackageFile = {
path: string
size: number
}
type InstalledPackage = {
name: string
version: string
size: number
files: PackageFile[]
license?: string
author?: { name?: string; email?: string; url?: string }
installedBy: { name: string; version: string }[]
level: number // 0 = direct dependency, 1+ = transitive
path: string
dependencySize: number
dependencyCount: number
}
type InstallSizeResult = {
packages: InstalledPackage[]
totalSize: number
installTime: number
packageManager: string
}
type InstallSizeOptions = {
// auto-detected by default
packageManager?: 'npm' | 'pnpm' | 'yarn'
// defaults to os.tmpdir()
tempDirectory?: string
}
function getInstallSize(
packages: string | string[],
options?: InstallSizeOptions
): Promise<InstallSizeResult>Analyze an existing node_modules directory:
import { analyzeNodeModules } from 'pkg-size'
// Analyze current directory's node_modules
const result = await analyzeNodeModules(process.cwd())
// Analyze specific project path
const otherResult = await analyzeNodeModules('/path/to/project')type PackageFile = {
path: string
size: number
}
type InstalledPackage = {
name: string
version: string
size: number
files: PackageFile[]
license?: string
author?: { name?: string; email?: string; url?: string }
installedBy: { name: string; version: string }[]
level: number // 0 = direct dependency, 1+ = transitive
path: string
dependencySize: number
dependencyCount: number
}
type NodeModulesAnalysis = {
packages: InstalledPackage[]
totalSize: number
}
function analyzeNodeModules(
projectPath: string
): Promise<NodeModulesAnalysis>A GitHub Action to automate package size regression reports on your pull requests—great for size-conscious development.