Registry / devops / fast-import-cost

fast-import-cost

library5.5.0jsnpmunverified

A CLI tool and Node.js library for calculating the bundle size of imported packages in JavaScript and TypeScript files. v5.5.0, actively maintained. Powered by esbuild and es-module-lexer, it offers fast scanning (50+ files in under 1 second) and provides minified, gzipped, and brotli sizes. Differentiators include tree-shaking awareness, a `--budget` flag for CI enforcement, diff support between git branches, and zero-config operation with npm, pnpm, yarn, and bun. Ships TypeScript definitions.

devops testing

npm install fast-import-cost

github ↗package ↗

INSTALL

IMPORT

SIG · FAST-IMPORT-COST

fast-import-cost

devopsjavascriptv5.5.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

importCost

✓ import { importCost } from 'fast-import-cost'

✗ const importCost = require('fast-import-cost')

ESM-only; CommonJS require will not work. Named export, not default.

Lang

✓ import { Lang } from 'fast-import-cost'

✗ import { Language } from 'fast-import-cost'

Enum with values JAVASCRIPT, TYPESCRIPT, VUE, SVELTE.

cleanup

✓ import { cleanup } from 'fast-import-cost'

Must be called to free esbuild resources when done.

PackageInfo

✓ import type { PackageInfo } from 'fast-import-cost'

✗ import { PackageInfo } from 'fast-import-cost'

TypeScript only type import. Using value import will fail at runtime.

Demonstrates the library API: importCost emitter with start, calculated, done, and error events, plus cleanup.

import { importCost, cleanup, Lang } from 'fast-import-cost'; import type { PackageInfo } from 'fast-import-cost'; const fileName = '/path/to/project/src/app.ts'; const fileContents = ` import express from 'express'; import { createServer } from 'http'; import { ApolloServer } from '@apollo/server'; import * as lodash from 'lodash'; `; const emitter = importCost(fileName, fileContents, Lang.TYPESCRIPT); emitter.on('start', (packages: PackageInfo[]) => { console.log('Calculating sizes for', packages.length, 'packages'); }); emitter.on('calculated', (pkg: PackageInfo) => { console.log(`${pkg.name}: ${(pkg.size / 1024).toFixed(2)} KB (gzip: ${(pkg.gzip / 1024).toFixed(2)} KB, brotli: ${(pkg.brotli / 1024).toFixed(2)} KB)`); console.log('Tree-shakeable:', pkg.sideEffects === false); }); emitter.on('done', (packages: PackageInfo[]) => { console.log('All done!'); const total = packages.reduce((sum, p) => sum + p.size, 0); console.log('Total size:', (total / 1024).toFixed(2), 'KB'); }); emitter.on('error', (e: Error) => { console.error('Error:', e.message); }); // Later when done emitter.removeAllListeners(); cleanup();

import-cost --version

Debug

Known issues

gotchaThe importCost function returns an EventEmitter that must be cleaned up with cleanup() to avoid resource leaks.

fix

Call cleanup() after the emitter emits 'done' or when shutting down your application.

affects: >=1.0.0

gotchaThe fileName must be an absolute path to the file being analyzed; relative paths will cause resolution failures.

fix

Use path.resolve() to get an absolute path before passing to importCost.

affects: >=1.0.0

gotchaThe 'start' event may fire with an empty array if no imports are detected; handle this case to avoid confusion.

fix

Check packages.length in the 'start' event handler before proceeding.

affects: >=1.0.0

gotchaESM-only package; using CommonJS require will throw a runtime error. TypeScript users must set moduleResolution to 'node16' or 'bundler'.

fix

Use import statements instead of require(); configure tsconfig.json appropriately.

affects: >=5.0.0

gotchaThe CLI --budget flag sets a size limit in KB. If any import exceeds this, the process exits with code 1. Useful for CI, but note that the budget checks individual imports, not total bundle size.

fix

Ensure --budget value is realistic for individual packages, or use --json to custom parse results.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'fast-import-cost'

Package not installed or ESM-only package imported via require.

fix

Install the package: npm install fast-import-cost. Then use import { ... } from 'fast-import-cost' instead of require().

TypeError: cleanup is not a function

Called cleanup() incorrectly or before importing.

fix

Ensure you import cleanup: import { cleanup } from 'fast-import-cost'; then call cleanup() after emitter is done.

Error: File not found: /path/relative/file.ts

fileName passed to importCost is a relative path instead of absolute.

fix

Use path.resolve(__dirname, 'file.ts') to get absolute path before passing to importCost.

Error: Event emitter memory leak detected. 11 listeners added to [EventEmitter]. Use emitter.setMaxListeners() to increase limit

Multiple importCost emitters created without removing listeners, leading to memory leak warnings.

fix

Call emitter.removeAllListeners() on old emitters before creating new ones, or increase max listeners if appropriate.

Upgrade

Version history

5.5.0latest on npm

Audit

Dependencies

esbuildrequiredUsed internally for bundling and size calculation

es-module-lexerrequiredUsed for static analysis of import statements

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/ruban-s/import-cost ↗

packagehttps://www.npmjs.com/package/fast-import-cost ↗