Bundle Collapser

Bundle Collapser is a browserify bundle optimization tool that converts file path-based require() calls to numeric ID-based calls to reduce bundle size. It replaces string require calls like require('./foo.js') with numeric ID calls like require(2), resulting in smaller, more compressible bundles.

Package Information

• Package Name: bundle-collapser
• Package Type: npm
• Language: JavaScript
• Installation: npm install bundle-collapser

Core Imports

const collapse = require('bundle-collapser');

Basic Usage

const collapse = require('bundle-collapser');
const fs = require('fs');

// Read a browserify bundle
const src = fs.readFileSync('bundle.js', 'utf8');

// Collapse the bundle and pipe to output
collapse(src).pipe(process.stdout);

Capabilities

Bundle Collapse Function

Processes a browserify bundle source string and returns a readable stream with collapsed require() calls.

/**
 * Collapse a browserify bundle by converting string require() calls to numeric IDs
 * @param {string} src - Bundle source code to process
 * @returns {Stream} Readable stream from browser-pack with collapsed require() calls
 */
function collapse(src);

Usage Example:

const collapse = require('bundle-collapser');
const fs = require('fs');

const bundleSource = fs.readFileSync('input-bundle.js', 'utf8');
const outputStream = collapse(bundleSource);

// Pipe to file
outputStream.pipe(fs.createWriteStream('collapsed-bundle.js'));

// Or collect the output
const concat = require('concat-stream');
outputStream.pipe(concat(function(collapsedBundle) {
  console.log('Collapsed bundle size:', collapsedBundle.length);
}));

Browserify Plugin Integration

Bundle Collapser can be used as a browserify plugin to automatically collapse bundles during the build process.

/**
 * Browserify plugin function that integrates bundle collapsing into the browserify pipeline
 * @param {Object} b - Browserify bundle instance
 * @param {Object} opts - Plugin options (currently unused)
 * @returns {void} Modifies browserify pipeline in place
 */
function apply(b, opts);
// Available via: require('bundle-collapser/plugin')

Usage Examples:

Command line:

browserify -p bundle-collapser/plugin main.js > collapsed-bundle.js

Programmatic:

const browserify = require('browserify');
const plugin = require('bundle-collapser/plugin');

browserify('main.js')
  .plugin(plugin)
  .bundle()
  .pipe(process.stdout);

Command Line Interface

Bundle Collapser includes a command-line tool for processing browserify bundles.

# Process a file
bundle-collapser input-bundle.js > collapsed-bundle.js

# Process from stdin
cat bundle.js | bundle-collapser > collapsed-bundle.js

# Process stdin with dash
bundle-collapser - > collapsed-bundle.js

# Specify input and output files
bundle-collapser -i input.js -o output.js

# Show help
bundle-collapser --help

CLI Options:

• -h, --help: Show usage information
• -i, --infile <file>: Input bundle file (defaults to stdin)
• -o, --outfile <file>: Output file (defaults to stdout)

Usage Notes:

• Input file can be specified as first positional argument or via -i/--infile option
• Use - as filename to explicitly specify stdin/stdout
• If no input file specified, reads from stdin
• If no output file specified, writes to stdout

Architecture

Bundle Collapser works by:

1. Unpacking: Using browser-unpack to parse the browserify bundle structure
2. Transformation: Using falafel (AST parser) to find and replace require() calls in each module
3. ID Mapping: Converting string-based dependency references to numeric IDs based on the dependency graph
4. Repacking: Using browser-pack to generate the optimized bundle with numeric require() calls

The transformation process preserves the functionality while reducing bundle size by replacing verbose string paths with compact numeric identifiers.

Bundle Optimization Benefits

• Size Reduction: Numeric IDs are shorter than file paths, reducing overall bundle size
• Better Compression: Repeated numeric patterns compress more efficiently than varied string paths
• Minification Friendly: Numeric require() calls work better with JavaScript minifiers
• Performance: Smaller bundles load faster and use less bandwidth

Error Handling

Bundle Collapser processes valid browserify bundles and will emit errors for invalid input. Common error scenarios include:

Input Validation:

• Malformed bundles or non-browserify JavaScript files may cause parsing errors
• Invalid or corrupted bundle metadata will prevent processing
• Non-standard require() call patterns may not be transformed correctly

Expected Input Format:

• Valid browserify bundle format (as output by browser-pack)
• Properly structured dependency information in the bundle metadata
• Standard require() call patterns that can be safely transformed

Error Handling in Code:

const collapse = require('bundle-collapser');
const fs = require('fs');

try {
  const bundleSource = fs.readFileSync('bundle.js', 'utf8');
  const outputStream = collapse(bundleSource);
  
  outputStream.on('error', (err) => {
    console.error('Bundle processing error:', err);
  });
  
  outputStream.pipe(process.stdout);
} catch (err) {
  console.error('Failed to read bundle file:', err);
}

For best results, ensure input files are valid browserify bundles created with standard browserify tooling.