Compare current sourcemap to the previous to understand why it changed in size.
A powerful tool that helps you analyze JavaScript bundle size changes by comparing source maps.
- Input can be local filenames or URLs to JavaScript files online
- Output can be HTML, JSON, or colorized command line text
- Full TypeScript support and ESM compatibility
# Using npm
npm install source-map-diff
# Using yarn
yarn add source-map-diff
import {
sourceMapDiff,
sourceMapDiffAsHtml,
sourceMapDiffForConsole
} from 'source-map-diff';
// Basic comparison returning structured data
async function compareBuilds() {
const result = await sourceMapDiff({
previousSrc: './dist/previous-build.js',
currentSrc: './dist/current-build.js'
});
console.log('Total files changed:', result.length);
}
// Generate HTML output
async function generateHtmlReport() {
const html = await sourceMapDiffAsHtml({
previousSrc: 'https://example.com/previous.js',
currentSrc: './dist/current.js'
});
// Write to file or insert into a webpage
console.log(html);
}
// Console output with colors
async function logToConsole() {
const output = await sourceMapDiffForConsole({
previousSrc: './dist/v1.0.0.js',
currentSrc: './dist/v1.1.0.js'
});
// Already formatted with colors for terminal display
console.log(output);
}
Returns a Promise
for HTML output that can be put on a web page. Classnames are included but not styling.
import { sourceMapDiffAsHtml } from 'source-map-diff';
const html = await sourceMapDiffAsHtml({
previousSrc: './dist/bundle.v1.js',
currentSrc: './dist/bundle.v2.js'
});
Returns a Promise
for color console output.
import { sourceMapDiffForConsole } from 'source-map-diff';
const consoleOutput = await sourceMapDiffForConsole({
previousSrc: 'https://mysite.com/v1/main.js',
currentSrc: 'https://mysite.com/v2/main.js'
});
console.log(consoleOutput);
Returns a Promise
for structured data you can use for custom reporting:
import { sourceMapDiff } from 'source-map-diff';
// Type of the returned data
interface FileSizeComparison {
filename: string;
added: boolean; // File was not in the previous bundle
removed: boolean; // File was removed from the current bundle
isIncreased: boolean; // File grew in size
isDecreased: boolean; // File decreased in size
isSame: boolean; // File did not change size
previousSize: number; // Byte count in previous bundle
currentSize: number; // Byte count in current bundle
changeInSize: number; // Change in bytes
}
// Example usage
const result = await sourceMapDiff({
previousSrc: './old.js',
currentSrc: './new.js'
});
// Find files with the biggest increases
const increases = result
.filter(item => item.isIncreased)
.sort((a, b) => b.changeInSize - a.changeInSize);
console.table(increases);
Basic usage:
# Compare local files
npx source-map-diff --previousSrc ./dist/old.js --currentSrc ./dist/new.js
# Compare with URLs
npx source-map-diff \
--previousSrc https://mysite.com/v1/bundle.js \
--currentSrc https://mysite.com/v2/bundle.js
# HTML output (useful for reports)
npx source-map-diff --previousSrc <file> --currentSrc <file> --format html > report.html
# JSON output (useful for further processing)
npx source-map-diff --previousSrc <file> --currentSrc <file> --format json > changes.json
# Default console output with colors
npx source-map-diff --previousSrc <file> --currentSrc <file>
- CI/CD Pipelines: Add bundle size tracking to your CI process
- Pull Request Reviews: Analyze bundle size impact before merging code
- Dependency Updates: Understand the impact of dependency upgrades
- Bundle Optimization: Identify opportunities for code splitting and tree-shaking
- Technical Debt: Track growing modules that need refactoring
- Size is always uncompressed bytes in the bundle, not size of the original source code.
- Bundlers often add helper functions and references to chunks/functions in other bundles, but don't include this data in the source map. We use "[generated]" to represent that code.
- You can compare any two bundles, even from different websites. Compare your JS to a competitor's site and see what dependencies you have in common.
- source-map-explorer - Create a visualization from the sourcemap. Source-map-diff uses this library to parse the source maps.