pkgroll: Zero-Config Rollup Bundler

2.27.0 · active · verified Sun Apr 19

pkgroll is a robust JavaScript package bundler built on Rollup, designed for zero-configuration builds by leveraging existing `package.json` fields like `main`, `module`, `types`, and `exports`. It streamlines the process of transforming TypeScript/ESM source code into various output formats, including ESM, CommonJS, and TypeScript declaration files (`.d.ts`). Currently stable at version 2.27.0, pkgroll maintains a frequent release cadence, with multiple bug fixes and minor feature additions observed monthly. Its key differentiators include automatic dependency externalization, built-in minification, comprehensive TypeScript support with `.d.ts` bundling, watch mode for development, and intelligent CLI output features such as hashbang insertion for executables. It simplifies package publishing by reducing the need for extensive build configurations.

Common errors

```
Error: Cannot find module 'typescript'
```
cause The `typescript` peer dependency is not installed in the project.

fix Install TypeScript: `npm install --save-dev typescript` or `pnpm add -D typescript`.
```
Error: Wildcard pattern must include a file extension (e.g. `*.mjs`)
```
cause A wildcard pattern in `package.json#exports` is missing a file extension.

fix Modify the `exports` entry to include a file extension, for example: `"./utils/*": "./dist/utils/*.mjs"`.
```
Error: Unknown export field 'exports.require.types'
```
cause Using advanced `package.json#exports` features (like nested conditions or specific `types` exports) with an older Node.js version that doesn't support them, or a malformed `package.json` structure.

fix Update Node.js to a version that fully supports `package.json#exports` (Node.js 14.13+ for most features, 16+ for full stable support). Review `package.json` for syntax errors.

Warnings

gotcha pkgroll has a peer dependency on TypeScript. Ensure you install a compatible version (e.g., `^4.1` or `^5.0`). While v2.27.0 supports TypeScript 6, older versions of pkgroll or incompatible TypeScript installations can lead to build failures.
Fix: Install a compatible TypeScript version: `npm install --save-dev typescript@"^5.0"` or `npm install --save-dev typescript@"^4.1"` as required by your pkgroll version.
gotcha pkgroll automatically maps output paths defined in `package.json` (e.g., `./dist/index.cjs`) to source files (e.g., `./src/index.ts`). Ensure your source file structure aligns with these inferred mappings, or use the `--srcdist` flag for custom source/distribution directory mappings.
Fix: Place source files corresponding to `dist` outputs in a `src` directory (e.g., `src/index.ts` for `dist/index.cjs`), or use `pkgroll --srcdist 'my-src:my-dist'` to define custom mappings.
gotcha When using wildcard patterns in `package.json#exports` (e.g., `./utils/*`), it is critical to include a file extension in the pattern (e.g., `./dist/utils/*.mjs`). Failing to do so will result in an error as pkgroll requires explicit file extensions for wildcard resolution.
Fix: Always specify a file extension in wildcard export patterns: `"./utils/*": "./dist/utils/*.mjs"`.
gotcha pkgroll relies heavily on `package.json` `exports` field for defining entry points and output formats. Incorrect or incomplete configuration of `exports`, especially regarding `import` and `require` conditions, can lead to incorrect bundling or runtime issues in consumers.
Fix: Consult Node.js documentation on `package.json#exports` and ensure all required conditions (`import`, `require`, `types`) are correctly specified for each entry point to support all target environments.

Install

npm install pkgroll npm
yarn add pkgroll yarn
pnpm add pkgroll pnpm

Quickstart

This quickstart demonstrates how to configure `package.json` for `pkgroll` to define entry points and output formats, then run the build.

{
    "name": "my-package",
    "version": "1.0.0",
    "type": "module",
    "main": "./dist/index.cjs",
    "module": "./dist/index.mjs",
    "types": "./dist/index.d.ts",
    "exports": {
        ".": {
            "require": {
                "types": "./dist/index.d.cts",
                "default": "./dist/index.cjs"
            },
            "import": {
                "types": "./dist/index.d.mts",
                "default": "./dist/index.mjs"
            }
        },
        "./foo": {
            "import": "./dist/foo.mjs",
            "require": "./dist/foo.cjs"
        }
    },
    "scripts": {
        "build": "pkgroll"
    },
    "devDependencies": {
        "pkgroll": "^2.0.0",
        "typescript": "^5.0.0"
    }
}
// To run the build:
npm install
npm run build

view raw JSON →