pkgroll

library2.27.0jsnpmunverified

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.

devops

npm install pkgroll

github ↗package ↗

INSTALL

IMPORT

SIG · PKGROLL

pkgroll

devopsjavascriptv2.27.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

pkgroll --version

Debug

Known issues

gotchapkgroll 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.

affects: >=2.0.0

gotchapkgroll 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.

affects: >=2.0.0

gotchaWhen 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"`.

affects: >=2.0.0

gotchapkgroll 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.

affects: >=2.0.0

Errors

Common errors & fixes

Error: Cannot find module 'typescript'

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`)

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'

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.

Upgrade

Version history

2.27.0latest on npm

Audit

Dependencies

typescriptrequiredPeer dependency required for TypeScript compilation and declaration file generation.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/privatenumber/pkgroll ↗

packagehttps://www.npmjs.com/package/pkgroll ↗