pkgroll: Zero-config JavaScript package bundler

Install pkgroll as a development dependency in your project:

npm install --save-dev pkgroll

Once installed, you can run it directly via npx pkgroll or add it to your package.json scripts.

npm install --save-dev pkgroll

Sources: README.md

The externalizeDependencies plugin accepts optional configuration:

{
  skipUnlistedWarnings?: boolean; // Skip warnings for unlisted dependencies
  forTypes?: boolean;             // Enable @types package warnings
}

• skipUnlistedWarnings: Useful for type declaration builds where imports may not match runtime dependencies. Prevents warnings when bundling unlisted packages.
• forTypes: Enables specific warnings about @types package mismatches. Only relevant when building type definitions.

These options are typically set internally by pkgroll based on the build context.

Sources: src/rollup/plugins/externalize-dependencies.ts

Use the --define flag to replace specific strings in your code at build time. This is useful for dead code elimination and conditional compilation.

pkgroll --define.process.env.NODE_ENV='"production"' --define.DEBUG=false

Note: Unlike --env, values are not automatically JSON stringified, so you need to include quotes for string values.

pkgroll --define.process.env.NODE_ENV='"production"' --define.DEBUG=false

Sources: README.md

pkgroll automatically externalizes dependencies based on their classification in package.json:

• dependencies, peerDependencies, optionalDependencies: Always externalized. These are treated as runtime dependencies and are not bundled.
• devDependencies: Bundled by default if resolvable. If a devDependency is not resolvable, the build fails with an error.
• Unlisted dependencies: Bundled with a warning to prevent runtime failures.

This behavior ensures that your published package only includes code necessary for its runtime, while relying on the consumer's environment for declared dependencies.

Sources: src/rollup/plugins/externalize-dependencies.ts

If pkgroll fails to read your project configuration, it may throw a parsing error. The tool attempts to load package.json or package.yaml from the project directory. If the file exists but contains invalid JSON or YAML syntax, pkgroll will throw an error with the message: Failed to parse <path>: <error message>. Ensure your package.json or package.yaml is valid and properly formatted.

Sources: src/utils/read-package.ts

If using packages with native modules (e.g., chokidar which depends on fsevents):

• In dependencies/peerDependencies: Works automatically (externalized).
• In devDependencies: Bundled. If they use bindings() or node-pre-gyp, move them to dependencies to avoid build errors.

Example:

{
    "dependencies": {
        "chokidar": "^3.0.0"
    }
}

Note: Native modules are platform and architecture-specific. Ensure you distribute the correct .node files for your target platforms.

{
    "dependencies": {
        "chokidar": "^3.0.0"
    }
}

Sources: README.md

You can use wildcard patterns in exports to bundle multiple modules automatically. Patterns must include a file extension (e.g., .mjs, .cjs).

Example:

{
    "exports": {
        "./utils/*": "./dist/utils/*.mjs",
        "./components/*/index": "./dist/components/*/index.mjs"
    }
}

This maps:

• src/utils/format.ts → dist/utils/format.mjs
• src/components/button/index.ts → dist/components/button/index.mjs

pkgroll automatically externalizes dependencies based on their type in package.json:

• Externalized: peerDependencies, dependencies, optionalDependencies
• Bundled: devDependencies

When generating type declarations (.d.ts), type dependencies in devDependencies are also bundled and tree-shaken.

Example:

{
    "peerDependencies": {
        "react": "^18.0.0"
    },
    "dependencies": {
        "lodash": "^4.17.21"
    },
    "devDependencies": {
        "typescript": "^5.0.0"
    }
}

In this case, react and lodash are externalized, while typescript is bundled.

{
    "dependencies": {
        "lodash": "^4.17.21"
    }
}

Sources: README.md