Registry / devops / package-build-stats

package-build-stats

JSON →
library8.2.7jsnpmunverified

package-build-stats is a JavaScript/TypeScript library designed to analyze the build size and performance metrics of npm packages. It simulates a package build process, including installation, minification (with Terser or esbuild), and gzipping, to provide detailed statistics such as gzipped size, uncompressed size, and bundle composition. The library is currently at version 8.2.7 and demonstrates an active release cadence with frequent updates and improvements. A key differentiator is its ability to utilize various package managers like Bun, pnpm, or Yarn for faster installations, and its beta support for analyzing local packages during development. It also allows for granular analysis by specifying custom top-level exports, beyond just the default export, and exposes a comprehensive event queue for monitoring build lifecycle events. This tool is the robust backend engine behind services like Bundlephobia, making it suitable for production use cases requiring accurate package size insights.

npm install package-build-stats
INSTALL
IMPORT
SIG · PACKAGE-BUILD-STAT
P
package-build-stats
devopsjavascriptv8.2.7
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

getPackageStats
import { getPackageStats } from 'package-build-stats'
const getPackageStats = require('package-build-stats')
This library is ESM-only (ES Modules) since v8.0.0; CommonJS 'require()' is not supported for its API.
eventQueue
import { eventQueue } from 'package-build-stats'
const { eventQueue } = require('package-build-stats')
Used to subscribe to various lifecycle events emitted during the package analysis process.
PackageStatsResult, BuildOptions
import type { PackageStatsResult, BuildOptions } from 'package-build-stats'
TypeScript types are shipped with the package to enhance developer experience.

This quickstart demonstrates how to import and utilize the `getPackageStats` function with various options, including custom package managers and specific imports, while also showing how to subscribe to lifecycle events for real-time feedback during package analysis.

import { getPackageStats, eventQueue } from 'package-build-stats'; // Listen to all lifecycle events during the build process eventQueue.on('*', (eventName, data) => { console.log(`[Event] ${eventName}:`, data); }); async function analyzePackage() { try { console.log('Analyzing moment@latest with Bun...'); const results = await getPackageStats('moment', { client: 'bun', // Use Bun for faster installs minifier: 'esbuild', // Faster minification customImports: ['default', 'localeData'], // Analyze specific exports installTimeout: 60000 // Increase timeout for potentially slow installs }); console.log('\n--- Build Stats for moment ---'); console.log(`Package: ${results.name}@${results.version}`); console.log(`Minified size (gzipped): ${results.gzip} bytes`); console.log(`Minified size (uncompressed): ${results.size} bytes`); console.log('Details:', JSON.stringify(results, null, 2)); // Example for a specific version console.log('\nAnalyzing lodash@4.17.21 with pnpm...'); const lodashResults = await getPackageStats('lodash@4.17.21', { client: 'pnpm' }); console.log(`Package: ${lodashResults.name}@${lodashResults.version}`); console.log(`Minified size (gzipped): ${lodashResults.gzip} bytes`); } catch (error) { console.error('Failed to analyze package:', error); if (error instanceof Error) { console.error(error.message); } } } analyzePackage();
Debug
Known issues
breakingVersion 8.0.0 introduced breaking changes requiring Node.js version 20.0.0 or higher and npm version 10.0.0 or higher. Older runtime environments will fail.
fix
Upgrade your Node.js installation to v20.0.0+ and npm to v10.0.0+ before using package-build-stats v8 or newer.
affects: >=8.0.0
breakingSince v8.0.0, package-build-stats is an ESM-only library. CommonJS 'require()' statements for importing the library will no longer work and will result in errors.
fix
Migrate your import statements from 'const { symbol } = require("package-build-stats")' to 'import { symbol } from "package-build-stats"'.
affects: >=8.0.0
gotchaInitial releases of v8.0.0 and v8.0.1 had issues with missing internal loader dependencies which could lead to build failures for certain package types (e.g., Less, Svelte).
fix
Ensure you are using v8.0.1 or a newer version to benefit from the bug fixes addressing these missing dependencies.
affects: 8.0.0, 8.0.1
gotchaPrior to v8.0.3, the library might incorrectly resolve to CommonJS (CJS) files instead of ESM for certain packages with 'node' condition before 'import' in their conditional exports, breaking `export * from` patterns.
fix
Update to `package-build-stats` v8.0.3 or higher, which includes a fix to correctly prioritize ESM exports.
affects: <8.0.3
gotchaThe default `installTimeout` (30 seconds, increased to 45 seconds in v7.3.12) can be insufficient for very large packages or slow network conditions, leading to installation failures.
fix
Increase the `installTimeout` option in `getPackageStats` (e.g., `installTimeout: 60000`). For faster installs, consider using `client: 'bun'` or `client: 'pnpm'`.
affects: >=7.0.0
Errors
Common errors & fixes
TypeError: require is not a function
Attempting to use CommonJS `require()` syntax in an ESM-only module (v8.0.0+).
fix
Change your import from `const { getPackageStats } = require('package-build-stats');` to `import { getPackageStats } from 'package-build-stats';`.
Error: Command failed with exit code 1: npm install ... (or similar timeout error)
The package installation process timed out or failed due to network issues/package size.
fix
Increase the `installTimeout` option in `getPackageStats` (e.g., `{ installTimeout: 90000 }`). Consider using a faster package client like `client: 'bun'` or `client: 'pnpm'`.
Error: Cannot find module 'css-loader' or 'sass-loader' etc. from '...'
Missing internal loader dependencies, especially if running older v8.0.x versions.
fix
Ensure `package-build-stats` is updated to at least v8.0.1, which patched these missing dependencies.
UnhandledPromiseRejectionWarning: Error: Cannot find module '...' from '...' (incorrect module resolution)
The library might be incorrectly resolving to CommonJS files instead of ESM due to a specific package's 'exports' field configuration.
fix
Update to `package-build-stats` v8.0.3 or higher. This version includes a fix for resolving ESM exports correctly when 'node' condition is present.
Upgrade
Version history
8.2.7latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
9 hits · last 30 days
node
6
Amazon
1
Resources
package-build-stats — npm install package-build-stats · libregistry