npm-auto-bundler

🚀 Zero-config, production-ready bundler for modern NPM packages

Automatically bundle your TypeScript/JavaScript packages with ESM, CJS, and TypeScript declarations. Perfect for library authors who want to focus on code, not build configuration.

✨ Features

• Zero Configuration - Works out of the box with sensible defaults
• Multi-format Output - ESM, CJS, and TypeScript declarations
• Smart Analysis - Auto-detects TypeScript, JSX, entry points, and dependencies
• Plugin System - Extensible with custom hooks and plugins
• Bundle Analysis - Built-in size analysis and health checks
• Package.json Updates - Automatically updates main, module, types, and exports fields
• Presets - Pre-configured setups for React, Vue, Node.js, and more
• CLI Interface - Easy command-line usage
• GitHub Actions Ready - Includes CI/CD workflows

🚀 Quick Start

Installation

npm install npm-auto-bundler

Basic Usage

# Bundle your package
npx npm-auto-bundler

# Or use the CLI
npm-auto-bundler

Programmatic Usage

import { NpmAutoBundler } from 'npm-auto-bundler';

const bundler = new NpmAutoBundler();
const result = await bundler.build({
  analyze: true,
  formats: ['esm', 'cjs'],
  minify: true
});

console.log('Bundle size:', result.stats.totalSize);

📦 What It Does

1. Analyzes your project structure and dependencies
2. Bundles your code to ESM and CJS formats
3. Generates TypeScript declarations
4. Updates package.json with correct entry points
5. Provides bundle analysis and optimization tips

🎯 Supported Formats

• ESM (ES Modules) - Modern JavaScript modules
• CJS (CommonJS) - Node.js compatibility
• TypeScript Declarations - .d.ts files for type safety

⚙️ Configuration

CLI Options

npm-auto-bundler [options]

Options:
  -e, --entry <path>        Entry point file
  -o, --out-dir <dir>       Output directory (default: dist)
  -f, --formats <formats>   Output formats: esm,cjs (default: auto-detect)
  -m, --minify              Minify output (default: true)
  -s, --sourcemap           Generate source maps (default: true)
  -a, --analyze             Show bundle analysis (default: true)
  -p, --preset <name>       Use preset: react,vue,node,universal,typescript,minimal
  -e, --external <pkg>      Mark package as external
  --no-update-package-json  Skip package.json updates
  --backup                  Create backup before updating package.json
  --dry-run                 Show what would be updated without making changes
  -h, --help                Show help

Programmatic Options

interface BuildOptions {
  entry?: string;                    // Entry point
  outDir?: string;                   // Output directory
  formats?: ('esm' | 'cjs')[];       // Output formats
  minify?: boolean;                  // Minify output
  sourcemap?: boolean;               // Generate source maps
  analyze?: boolean;                 // Show analysis
  preset?: string;                   // Use preset
  external?: string[];               // External dependencies
  updatePackageJson?: boolean;       // Update package.json
  backupPackageJson?: boolean;       // Create backup
  dryRun?: boolean;                  // Dry run mode
}

🎨 Presets

React

npm-auto-bundler --preset react

• ESM + CJS formats
• React and React-DOM as externals
• JSX support enabled
• Bundle analysis enabled

Vue

npm-auto-bundler --preset vue

• ESM + CJS formats
• Vue as external
• Bundle analysis enabled

Node.js

npm-auto-bundler --preset node

• CJS format only
• Node.js built-ins as externals
• No minification
• No bundle analysis

Universal

npm-auto-bundler --preset universal

• ESM + CJS formats
• Optimized for both browser and Node.js
• Bundle analysis enabled

TypeScript

npm-auto-bundler --preset typescript

• ESM + CJS formats
• TypeScript declarations
• Bundle analysis enabled

Minimal

npm-auto-bundler --preset minimal

• ESM format only
• No minification
• No source maps
• No analysis

🔌 Plugin System

Built-in Plugins

• Bundle Analyzer - Provides bundle size analysis
• Progress Indicator - Shows bundling progress

Custom Plugins

import { PluginManager } from 'npm-auto-bundler';

const pluginManager = new PluginManager();

pluginManager.register({
  name: 'my-plugin',
  version: '1.0.0',
  hooks: {
    beforeBuild: (options) => {
      // Modify build options
      return { ...options, customOption: true };
    },
    afterBuild: (results, stats) => {
      // Post-build processing
      console.log('Build completed!');
    }
  }
});

📊 Bundle Analysis

The bundler provides detailed analysis including:

• Total bundle size
• Format breakdown (ESM vs CJS)
• Dependency analysis
• Optimization suggestions
• Health score

Example output:

📊 Bundle Analysis Report
==================================================

Total Size: 45.2 KB

Format Breakdown:
  ESM: 22.1 KB
  CJS: 23.1 KB

Top Dependencies:
  lodash: 15.2 KB
  react: 8.1 KB

Health Score: 95/100

Recommendations:
  💡 Consider code splitting for large dependencies
  💡 Excellent tree-shaking efficiency

🔧 Advanced Usage

Custom Entry Points

const bundler = new NpmAutoBundler();
await bundler.build({
  entry: 'src/main.ts',
  outDir: 'build',
  formats: ['esm']
});

External Dependencies

await bundler.build({
  external: ['react', 'lodash'],
  formats: ['esm', 'cjs']
});

Package.json Updates

The bundler automatically updates your package.json:

{
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist"]
}

🧪 Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

📈 GitHub Actions

Include this workflow for automated bundling:

name: Bundle Package
on: [push, pull_request]
jobs:
  bundle:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm ci
      - run: npx npm-auto-bundler
      - run: npm test

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🚀 Roadmap

• [ ] Webpack support
• [ ] Rollup support
• [ ] CSS bundling
• [ ] Asset optimization
• [ ] Development server
• [ ] Hot module replacement

Made with ❤️ for the JavaScript community