Site | NPM Module | GitHub Repo

Prepare Package is a helpful NPM module that prepares your package before distribution.

Install

npm install prepare-package --save-dev

Quick Setup

Run the interactive CLI to configure your project:

npx pp

This will walk you through selecting a build type (copy or bundle), configuring formats, and auto-deriving IIFE settings (global name from package name in TitleCase, filename as {name}.min.js). The CLI writes the preparePackage config and scripts directly to your package.json.

You can also use the full name:

npx prepare-package

Features

• Two modes: copy (default) and bundle (esbuild)
• Copy mode: copies src/ to dist/, replaces {version} in main file
• Bundle mode: builds ESM, CJS, and/or IIFE outputs via esbuild
• Blocks npm publish when local file: dependencies are detected
• Cleans up sensitive files (.env, .DS_Store, etc.) before publish
• Purges jsDelivr CDN cache after publish
• Watch mode for both copy and bundle types
• Auto-adds prepare and prepare:watch scripts to consumer's package.json

Configuration

All configuration lives in the preparePackage key in your package.json.

Copy Mode (default)

Copies files from input to output and replaces {version} in the main file.

{
  "main": "dist/index.js",
  "preparePackage": {
    "input": "src",
    "output": "dist"
  }
}

Key	Default	Description
type	"copy"	Processing mode
input	"src"	Source directory to copy from
output	"dist"	Destination directory to copy to
replace	{}	Additional replacements (reserved)

Bundle Mode

Uses esbuild to produce optimized builds in multiple module formats.

{
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "preparePackage": {
    "input": "src",
    "output": "dist",
    "type": "bundle",
    "build": {
      "formats": ["esm", "cjs", "iife"],
      "iife": {
        "globalName": "MyLib",
        "fileName": "my-lib.min.js"
      }
    }
  }
}

Key	Default	Description
type	—	Must be "bundle" to enable this mode
build.entry	"{input}/index.js"	Entry point for esbuild
build.formats	["esm", "cjs"]	Output formats: "esm", "cjs", "iife"
build.target	"es2020"	esbuild target for ESM/CJS builds
build.platform	"neutral"	esbuild platform
build.external	[]	Packages to exclude from bundle
build.sourcemap	false	Generate source maps
build.cjs.footer	"module.exports=module.exports.default||module.exports;"	CJS footer — unwraps export default so require() returns the value directly
build.iife.globalName	—	Required when "iife" is in formats. The global variable name (e.g., window.MyLib)
build.iife.fileName	"{name}.min.js"	Output filename for IIFE build
build.iife.target	"es2015"	esbuild target for IIFE build

Output files

Format	File	Minified
ESM	dist/index.mjs	No
CJS	dist/index.js	No
IIFE	dist/{fileName}	Yes

Version replacement

In bundle mode, all occurrences of {version} in .js source files are replaced with the version from package.json at build time via an esbuild plugin.

CJS default export

The CJS build automatically appends a footer that unwraps export default so require('your-package') returns the function/class directly — not { default: fn }. This means both of these just work:

// ESM
import MyLib from 'your-package';

// CJS
const MyLib = require('your-package');

To override the footer, set build.cjs.footer in your config.

IIFE global export

The IIFE build automatically unwraps the default export so window[globalName] is the class/function directly, not a { default } wrapper.

Usage

# Build once
npm run prepare

# Watch for changes
npm run prepare:watch

# These scripts are auto-added to your package.json:
# "prepare": "node -e \"require('prepare-package')()\""
# "prepare:watch": "node -e \"require('prepare-package/watch')()\""

Publish Safety

When running via npm publish, prepare-package will:

1. Block local dependencies — fails if any file:, ../, ./, /, or ~ dependency versions are found
2. Remove sensitive files — deletes .env, .env.local, .env.development, .env.production, firebase-debug.log, .DS_Store, Thumbs.db from the package
3. Purge CDN cache — purges the jsDelivr cache for your package after publish

Questions

If you are still having difficulty, post a question to the Prepare Package issues page.