{"id":25575,"library":"fast-import-cost","title":"fast-import-cost","description":"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.","status":"active","version":"5.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/ruban-s/import-cost","tags":["javascript","import","require","size","cost","bundle","bundle-size","bundlesize","webpack","typescript"],"install":[{"cmd":"npm install fast-import-cost","lang":"bash","label":"npm"},{"cmd":"yarn add fast-import-cost","lang":"bash","label":"yarn"},{"cmd":"pnpm add fast-import-cost","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for bundling and size calculation","package":"esbuild","optional":false},{"reason":"Used for static analysis of import statements","package":"es-module-lexer","optional":false}],"imports":[{"note":"ESM-only; CommonJS require will not work. Named export, not default.","wrong":"const importCost = require('fast-import-cost')","symbol":"importCost","correct":"import { importCost } from 'fast-import-cost'"},{"note":"Enum with values JAVASCRIPT, TYPESCRIPT, VUE, SVELTE.","wrong":"import { Language } from 'fast-import-cost'","symbol":"Lang","correct":"import { Lang } from 'fast-import-cost'"},{"note":"Must be called to free esbuild resources when done.","wrong":null,"symbol":"cleanup","correct":"import { cleanup } from 'fast-import-cost'"},{"note":"TypeScript only type import. Using value import will fail at runtime.","wrong":"import { PackageInfo } from 'fast-import-cost'","symbol":"PackageInfo","correct":"import type { PackageInfo } from 'fast-import-cost'"}],"quickstart":{"code":"import { importCost, cleanup, Lang } from 'fast-import-cost';\nimport type { PackageInfo } from 'fast-import-cost';\n\nconst fileName = '/path/to/project/src/app.ts';\nconst fileContents = `\nimport express from 'express';\nimport { createServer } from 'http';\nimport { ApolloServer } from '@apollo/server';\nimport * as lodash from 'lodash';\n`;\n\nconst emitter = importCost(fileName, fileContents, Lang.TYPESCRIPT);\n\nemitter.on('start', (packages: PackageInfo[]) => {\n  console.log('Calculating sizes for', packages.length, 'packages');\n});\n\nemitter.on('calculated', (pkg: PackageInfo) => {\n  console.log(`${pkg.name}: ${(pkg.size / 1024).toFixed(2)} KB (gzip: ${(pkg.gzip / 1024).toFixed(2)} KB, brotli: ${(pkg.brotli / 1024).toFixed(2)} KB)`);\n  console.log('Tree-shakeable:', pkg.sideEffects === false);\n});\n\nemitter.on('done', (packages: PackageInfo[]) => {\n  console.log('All done!');\n  const total = packages.reduce((sum, p) => sum + p.size, 0);\n  console.log('Total size:', (total / 1024).toFixed(2), 'KB');\n});\n\nemitter.on('error', (e: Error) => {\n  console.error('Error:', e.message);\n});\n\n// Later when done\nemitter.removeAllListeners();\ncleanup();","lang":"typescript","description":"Demonstrates the library API: importCost emitter with start, calculated, done, and error events, plus cleanup."},"warnings":[{"fix":"Call cleanup() after the emitter emits 'done' or when shutting down your application.","message":"The importCost function returns an EventEmitter that must be cleaned up with cleanup() to avoid resource leaks.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use path.resolve() to get an absolute path before passing to importCost.","message":"The fileName must be an absolute path to the file being analyzed; relative paths will cause resolution failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Check packages.length in the 'start' event handler before proceeding.","message":"The 'start' event may fire with an empty array if no imports are detected; handle this case to avoid confusion.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use import statements instead of require(); configure tsconfig.json appropriately.","message":"ESM-only package; using CommonJS require will throw a runtime error. TypeScript users must set moduleResolution to 'node16' or 'bundler'.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Ensure --budget value is realistic for individual packages, or use --json to custom parse results.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install the package: npm install fast-import-cost. Then use import { ... } from 'fast-import-cost' instead of require().","cause":"Package not installed or ESM-only package imported via require.","error":"Error: Cannot find module 'fast-import-cost'"},{"fix":"Ensure you import cleanup: import { cleanup } from 'fast-import-cost'; then call cleanup() after emitter is done.","cause":"Called cleanup() incorrectly or before importing.","error":"TypeError: cleanup is not a function"},{"fix":"Use path.resolve(__dirname, 'file.ts') to get absolute path before passing to importCost.","cause":"fileName passed to importCost is a relative path instead of absolute.","error":"Error: File not found: /path/relative/file.ts"},{"fix":"Call emitter.removeAllListeners() on old emitters before creating new ones, or increase max listeners if appropriate.","cause":"Multiple importCost emitters created without removing listeners, leading to memory leak warnings.","error":"Error: Event emitter memory leak detected. 11 listeners added to [EventEmitter]. Use emitter.setMaxListeners() to increase limit"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}