PackItUp 📦

"Pack it up!" - A simple and straightforward JavaScript packager

✨ Features

• 🔄 Self-contained - Can pack itself, truly zero-dependency
• 🚀 Single file output - All code bundled into one file (or two files: UMD and ESM)
• ⚙️ Virtual module system - Built-in core module simulation
• 📁 Zero configuration - Works out of the box
• 🗺️ Source Map support - Generate source maps for debugging (optional)
• 🎯 Fine-grained control - Whitelist/blacklist files, mark external dependencies, customize entry

🚀 Quick Start

Install

npm install packitup
cd node_modules/packitup
node install
cd ../..

Now you can use the packitup command directly:

packitup build . ./dist --only-export "src node_modules"

📖 Usage

# Basic
packitup build <input-directory> [output-directory]

# With options
packitup build ./src ./dist --name my-app --umd bundle.js

# Enable source maps
packitup build ./src ./dist --source-map

# Custom source map file names
packitup build ./src ./dist --source-map --umd-source-map myapp.map

# Only include certain directories (whitelist)
packitup build . --only-export "src lib" --source-map

# Exclude specific files (blacklist)
packitup build . --dont-export "test/.* \\.spec\\.js"

# Mark external dependencies (not bundled)
packitup build ./src --externals "react,react-dom"

# Specify a custom entry file
packitup build ./src --main app.js

# Show help
packitup --help

⚙️ Options

Option Description --name Specify project name (default: directory name) --main Specify entry file name (default: index.js) --umd UMD output filename (default: [projectName].js) --esm ESM output filename (default: [projectName].mjs) --source-map Generate source map files (.map) alongside bundles --umd-source-map Custom filename for UMD source map --esm-source-map Custom filename for ESM source map --externals Comma-separated external dependencies (e.g., react,react-dom) --dont-export Space-separated regex patterns to exclude files from export --only-export Space-separated patterns to include (whitelist, e.g., "src lib") --global-export Global variable name for UMD build (default: project name) --move Enable path moving (requires --move-from and --move-to) --move-from Base path for moving files (used with --move-to) --move-to Target path for moving files (defaults to --move-from if omitted) --esm-template Custom ESM export template file --help Show this help message

🔧 API Usage

const { buildDirectory } = require('packitup');

const result = buildDirectory('./src', {
  projectName: 'my-app',
  main: 'app.js',               // entry file (default: index.js)
  extensions: ['.js', '.json'],
  sourceMap: true,              // generate source map data
  externals: ['react'],         // external dependencies
  onlyExport: ['src', 'lib'],   // whitelist directories
  dontExport: [/test\/.*/],     // blacklist patterns
});

console.log(result.umd);        // bundled UMD code
console.log(result.esm);        // bundled ESM code
console.log(result.locationMap); // source map location data (if enabled)

ESM import

import { buildDirectory } from 'packitup';

const result = buildDirectory('./src', {
  projectName: 'my-app',
  main: 'app.js',
  extensions: ['.js', '.json']
});

Global (browser) usage

const { buildDirectory } = PackItUp;

const result = buildDirectory('./src', {
  projectName: 'my-app',
  main: 'app.js',
  extensions: ['.js', '.json']
});

🗺️ Source Map Integration

When --source-map is enabled, PackItUp generates .map files alongside your bundles. These can be used with tools like terser to preserve debug ability after minification:

terser bundle.js --source-map "content='bundle.js.map'" -o bundle.min.js

📂 Example Project Structure

Suppose you have a project like this:

my-project/
├── src/
│   ├── index.js
│   ├── lib/
│   │   └── helper.js
│   └── utils.js
├── node_modules/
│   └── some-dependency/
└── package.json

PackItUp will recursively bundle all .js and .json files (plus any extensions you specify) under the input directory, preserving the module resolution behavior.

🤔 FAQ

Q: How do I get the packitup command after installation? A: Run node install inside the node_modules/packitup directory as shown in the Quick Start. This sets up the command for your environment.

Q: Which module systems are supported? A: Currently supports CommonJS (input) and can export to both UMD and ESM formats.

Q: Can I use PackItUp with minifiers? A: Yes. Generate source maps with --source-map, then pass them to your minifier. The minifier will produce a new source map that maps back to your original sources.

Q: What is the difference between --only-export and --dont-export? A: --only-export is a whitelist – only files matching the specified patterns will be included. --dont-export is a blacklist – files matching those patterns will be excluded. You can use both together; --only-export filters first, then --dont-export removes additional files from the result.

Q: How do I handle external dependencies like React? A: Use --externals "react,react-dom" to mark them as external. They will not be bundled, but rather expected to be provided by the host environment (e.g., via require('react') in Node or a global variable in the browser).

Q: Can I change the entry point? A: Yes, use --main to specify a different entry file (default is index.js).

📄 License

ISC License – see LICENSE file.

📌 About Version Numbers

This package does not have a 1.0.0 release. The name packitup was originally registered and published by someone else in 2018 with version 1.0.0. That package has long been deleted, but npm's registry history still retains the version record — so 1.0.0 can never be published again.

Version 2.0.0 introduces a breaking change: the build command now requires you to specify the entry point with . and use --only-export to include directories (e.g., src, node_modules). Previously, the src directory was selected directly and node_modules was included automatically.

As a result, packitup jumps from 0.4.0 straight to 2.0.0.