pkgroll

Zero-config package bundler for Node.js + TypeScript

Building tool
privatenumber/pkgrollpkgroll

README

pkgroll


_pkgroll_ is a JavaScript package bundler powered by Rollup that automatically builds your package from entry-points defined in package.json. No config necessary!

Write your code in TypeScript/ESM and run pkgroll to get ESM/CommonJS/.d.ts outputs!

Features

- ✅ package.json#exports to define entry-points
- ✅ Dependency externalization
- ✅ Minification
- ✅ TypeScript support + .d.ts bundling
- ✅ Watch mode
- ✅ CLI outputs (auto hashbang insertion)

Install


  1. ```sh
  2. npm install --save-dev pkgroll
  3. ```

Quick setup


1. Setup your project with source files in src and output in dist (configurable).

2. Define package entry-files in package.json.

    These configurations are for Node.js to determine how to import the package.

    Pkgroll leverages the same configuration to determine how to build the package.

json5
{
     "name": "my-package",

     // Set "module" or "commonjs" (https://nodejs.org/api/packages.html#type)
     // "type": "module",

     // Define the output files
     "main": "./dist/index.cjs",
     "module": "./dist/index.mjs",
     "types": "./dist/index.d.cts",

     // Define output files for Node.js export maps (https://nodejs.org/api/packages.html#exports)
     "exports": {
         "require": {
             "types": "./dist/index.d.cts",
             "default": "./dist/index.cjs"
         },
         "import": {
             "types": "./dist/index.d.mts",
             "default": "./dist/index.mjs"
         }
     },

     // bin files will be compiled to be executable with the Node.js hashbang
     "bin": "./dist/cli.js",

     // (Optional) Add a build script referencing pkgroll
     "scripts": {
         "build": "pkgroll"
     }

     // ...
}

Paths that start with ./dist/ are automatically mapped to files in the ./src/ directory.

3. Package roll!
sh
npm run build # or npx pkgroll

Usage


Entry-points

_Pkgroll_ parses package entry-points from package.json by reading properties main, module, types, and exports.

The paths in ./dist are mapped to paths in ./src (configurable with --src and --dist flags) to determine bundle entry-points.

Output formats

_Pkgroll_ detects the format for each entry-point based on the file extension or the package.json property it's placed in, using the same lookup logic as Node.js.

`package.json`Output
--
`main`Auto-detect
`module`ESM
Note:
`types`TypeScript
`exports`Auto-detect
`exports.require`CommonJS
`exports.import`Auto-detect
`exports.types`TypeScript
`bin`Auto-detect
Also