import-cost-total

Analyze total import costs across your TypeScript/JavaScript project

Problem

VSCode's "Import Cost" extension shows cost per file. But what's the TOTAL bundle impact across your entire project?

Solution

import-cost-total shows the total cost of all imports across your project, identifies the biggest dependencies, and suggests optimizations.

Features

✅ Total Bundle Analysis - See the full picture, not just per-file ✅ Watch Mode - Re-analyze on file changes during development ✅ History Tracking - Compare runs and track bundle size over time ✅ HTML Treemap - Visual report like webpack-bundle-analyzer ✅ GitHub Action - Block PRs that increase bundle size ✅ README Badges - Show bundle size in your project ✅ Duplicate Detection - Find packages with multiple versions ✅ Parallel API Requests - 5x faster analysis ✅ CI-Friendly Output - Markdown reports for PRs ✅ Actionable Suggestions - Replace heavy packages with alternatives

Installation

# Run directly with npx (recommended)
npx import-cost-total

# Or install globally
npm install -g import-cost-total

# Or install as dev dependency
npm install --save-dev import-cost-total

Usage

Basic Usage

# Analyze current directory
npx import-cost-total

# Analyze specific directory
npx import-cost-total --path ./my-project

# Show top 20 dependencies
npx import-cost-total --top 20

# Only show packages above 50KB
npx import-cost-total --threshold 50

# Output as JSON
npx import-cost-total --json

Watch Mode

Re-analyze automatically when files change:

npx import-cost-total --watch

Compare with Last Run

Track bundle size changes over time:

npx import-cost-total --diff

Output:

📊 Comparison with last run:
   📈 Bundle size: +15.2 KB (+8.3%)
   📦 Packages: +2
   Last run: 2/8/2026, 3:45:12 PM

HTML Treemap Report

Generate a visual report like webpack-bundle-analyzer:

npx import-cost-total --html report.html

Opens an interactive treemap showing package sizes and percentages.

README Badge

Generate a badge showing your project's bundle size:

npx import-cost-total --badge

Output:

📛 README Badge:

Total bundle size: 154.4 KB gzipped (684.2 KB raw) across 15 packages

Markdown:
![Bundle Size](https://img.shields.io/badge/bundle%20size-154.4KB-yellow?style=flat)

Duplicate Detection

Find packages installed with multiple versions:

npx import-cost-total --duplicates

Output:

⚠️  Found 3 package(s) with multiple versions:

   lodash: 4.17.21, 4.17.15
   uuid: 8.3.2, 9.0.0

   Run `npm dedupe` to flatten dependency tree

CI/CD Integration

Generate markdown reports for pull requests:

npx import-cost-total --ci

GitHub Action

Add this workflow to automatically check PRs for bundle size:

# .github/workflows/bundle-size.yml
name: Bundle Size Check

on:
  pull_request:
    paths:
      - 'package.json'
      - 'src/**'

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: willzhangfly/import-cost-total@v1
        with:
          threshold: 10        # Only report packages > 10KB
          max-size: 500        # Fail if total > 500KB

Example Output

📦 Total Import Cost Analysis:

┌───┬─────────────────────┬────────────────────┬────────┬────────────┐
│ # │ Package             │ Size (Gzip)        │ Files  │ % of Total │
├───┼─────────────────────┼────────────────────┼────────┼────────────┤
│ 1 │ moment              │ 70.7 KB (288.8 KB) │ 12     │ 45.8%      │
│ 2 │ lodash              │ 24.4 KB (72.5 KB)  │ 23     │ 15.8%      │
│ 3 │ chart.js            │ 67.8 KB (243.1 KB) │ 5      │ 43.9%      │
└───┴─────────────────────┴────────────────────┴────────┴────────────┘

📊 Summary:
   Total packages: 15
   Total files analyzed: 142
   Total bundle size: 154.4 KB (684.2 KB uncompressed)
   Top 3 contribute: 162.9 KB (105.5% of bundle)

💡 Optimization Suggestions:

   🔥 Replace moment → dayjs
      → Potential savings: 480.0 KB

   ⚡ Import specific functions for lodash
      → Potential savings: 250.0 KB

CLI Options

| Option | Description | Default | |--------|-------------|---------| | -p, --path <dir> | Project directory to analyze | cwd | | -w, --watch | Watch mode: re-analyze on changes | false | | --diff | Compare with last run | false | | --html <file> | Generate HTML treemap report | - | | --badge | Generate README badge | false | | --duplicates | Show duplicate packages | false | | --ci | CI-friendly markdown output | false | | --json | Output results as JSON | false | | --top <n> | Number of top dependencies to show | 10 | | --threshold <kb> | Only show packages above size (KB) | - | | --parallel <n> | Number of parallel API requests | 5 | | --no-cache | Disable caching | Enabled | | --no-suggestions | Hide optimization suggestions | Shown |

How It Works

1. Scans all JavaScript/TypeScript files in your project
2. Extracts import statements using regex parsing
3. Fetches package sizes from Bundlephobia API (with caching)
4. Aggregates costs by dependency
5. Suggests optimizations based on proven alternatives

vs. Other Tools

| Feature | import-cost-total | webpack-bundle-analyzer | Bundlephobia | |---------|-------------------|------------------------|--------------| | No build required | ✅ | ❌ | N/A | | Project-wide analysis | ✅ | ✅ | ❌ | | Watch mode | ✅ | ✅ | ❌ | | History tracking | ✅ | ❌ | ❌ | | GitHub Action | ✅ | ❌ | ❌ | | Suggestions | ✅ | ❌ | ❌ | | HTML treemap | ✅ | ✅ | ❌ | | Duplicate detection | ✅ | ❌ | ❌ |

Alternatives Database

The tool includes optimizations for popular packages:

• Date/Time: moment → date-fns, dayjs, Temporal API
• Utilities: lodash optimization patterns
• UI Libraries: Material-UI, Ant Design tree-shaking
• HTTP Clients: axios → native fetch
• Validation: validator → native APIs
• UUID: uuid → crypto.randomUUID()
• And many more...

Supported Package Managers

• npm
• yarn
• pnpm
• bun

Requirements

• Node.js 18.0.0 or higher

Related Projects

• Import Cost VSCode Extension - Shows import cost per file
• Bundlephobia - Find the cost of adding npm packages
• webpack-bundle-analyzer - Visualize webpack bundle

Support

If this tool helped reduce your bundle size, consider:

• ⭐ Starring the repo
• 📢 Sharing with your team
• ☕ Buy me a coffee

License

MIT

Made with ❤️ for better web performance