{"id":25754,"library":"import-cost-core","title":"import-cost-core","description":"Calculate the bundle size of imported packages in JavaScript and TypeScript with a CLI and Node.js API. Version 5.5.0, actively maintained (2025 release). Powered by esbuild and es-module-lexer for high performance — scans 50+ files in less than a second. Provides minified, gzipped, and brotli sizes; identifies tree-shakeable packages; supports budget enforcement, JSON output, ignore patterns, watch mode, and git diff for CI/CD. Works with npm, pnpm, yarn, and bun. Aims to be a drop-in replacement for the deprecated import-cost VS Code extension backend, offering more accuracy and speed than webpack-bundle-analyzer or cost-of-modules.","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 import-cost-core","lang":"bash","label":"npm"},{"cmd":"yarn add import-cost-core","lang":"bash","label":"yarn"},{"cmd":"pnpm add import-cost-core","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core bundler used for size calculation","package":"esbuild","optional":false},{"reason":"Fast ESM module analysis for tree-shaking detection","package":"es-module-lexer","optional":false}],"imports":[{"note":"Main function; returns an EventEmitter. Available since v1.","symbol":"importCost","correct":"import { importCost } from 'import-cost-core'"},{"note":"Enum for file language: Lang.JAVASCRIPT, Lang.TYPESCRIPT, Lang.VUE, Lang.SVELTE.","symbol":"Lang","correct":"import { Lang } from 'import-cost-core'"},{"note":"PackageInfo is a TypeScript type/interface, not a runtime value. Must use 'import type'.","wrong":"import { PackageInfo } from 'import-cost-core'","symbol":"PackageInfo","correct":"import type { PackageInfo } from 'import-cost-core'"},{"note":"Must be called on shutdown to terminate esbuild workers.","symbol":"cleanup","correct":"import { cleanup } from 'import-cost-core'"}],"quickstart":{"code":"import { importCost, cleanup, Lang } from 'import-cost-core';\nimport type { PackageInfo } from 'import-cost-core';\n\nconst fileName = 'src/index.ts';\nconst fileContents = `\nimport express from 'express';\nimport { readFile } from 'fs/promises';\nconst _ = require('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}: minified=${(pkg.size / 1024).toFixed(2)} KB, gzip=${(pkg.gzip / 1024).toFixed(2)} KB, brotli=${(pkg.brotli / 1024).toFixed(2)} KB, tree-shakeable=${pkg.sideEffects === false}`);\n});\n\nemitter.on('done', (packages: PackageInfo[]) => {\n  console.log('All done!');\n  cleanup();\n});\n\nemitter.on('error', (err: Error) => {\n  console.error('Error:', err.message);\n});","lang":"typescript","description":"Demonstrates API usage: scanning a TypeScript file for imports and logging size metrics with cleanup."},"warnings":[{"fix":"Call `emitter.removeAllListeners()` before creating a new emitter for the same file.","message":"The `importCost` function caches results based on file content. If you call it multiple times with the same content, you might get stale results. Dispose the emitter and create a new one for fresh calculations.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Use `import type { PackageInfo } from 'import-cost-core'` to import only the type, or use `import { PackageInfo } from 'import-cost-core'` only if you need the runtime value (it does not exist).","message":"The `PackageInfo` import is a TypeScript type, not a value. Attempting to use it at runtime will throw `ReferenceError: Cannot access 'PackageInfo' before initialization` in CommonJS or `PackageInfo is not defined` in ESM.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Replace `import importCost from 'import-cost-core'` with `import { importCost } from 'import-cost-core'`.","message":"The default export `import importCost from 'import-cost-core'` is deprecated as of v3.0. Use named imports instead.","severity":"deprecated","affected_versions":">=3.0"},{"fix":"Update to v3.0+ which restored the optional config parameter or adjust your calls to include the language parameter.","message":"In v2.0, the function signature changed: `importCost(fileName, fileContents, language)` replaced the old `importCost(fileName, fileContents, language, config)`. The config object is now passed as the fourth argument, but the third argument is now required (previously optional).","severity":"breaking","affected_versions":">=2.0 <3.0"},{"fix":"Call `cleanup()` when done, e.g., after the 'done' event or in a process 'exit' handler.","message":"The `cleanup` function must be called to terminate background esbuild workers. If you don't call it, the Node.js process will not exit cleanly (it will hang).","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use `import type { PackageInfo } from 'import-cost-core'` instead.","cause":"Importing `PackageInfo` as a value when it is only a TypeScript type.","error":"ReferenceError: Cannot access 'PackageInfo' before initialization"},{"fix":"Run `npm install import-cost-core` in your project.","cause":"Package not installed or not in node_modules.","error":"Error: Cannot find module 'import-cost-core'"},{"fix":"Use `import { importCost } from 'import-cost-core'`.","cause":"Using default import in ESM when package expects named export, or misconfiguring bundler.","error":"TypeError: importCost is not a function"},{"fix":"Run `npm install esbuild` alongside import-cost-core.","cause":"Missing peer dependency 'esbuild'.","error":"Error: esbuild is not installed"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}