or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-pkgroll

Zero-config rollup bundler that automatically builds packages from entry-points defined in package.json

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/pkgroll@2.15.x

To install, run

npx @tessl/cli install tessl/npm-pkgroll@2.15.0

pkgroll

pkgroll is a zero-configuration JavaScript package bundler powered by Rollup that automatically builds packages from entry-points defined in package.json. It transforms TypeScript/ESM source code into ESM, CommonJS, and TypeScript declaration outputs without requiring manual configuration.

Package Information

Package Name: pkgroll
Package Type: npm
Language: JavaScript/TypeScript
Node.js Version: >=18
TypeScript Support: Optional peer dependency (^4.1 || ^5.0)
Installation: npm install --save-dev pkgroll

Core Imports

pkgroll is a CLI tool only - it provides no programmatic API. All functionality is accessed through the command line interface.

Basic Usage

# Install as dev dependency
npm install --save-dev pkgroll

# Run with default configuration
npx pkgroll

# Or add to package.json scripts
{
  "scripts": {
    "build": "pkgroll"
  }
}
npm run build

Architecture

pkgroll operates by:

Entry Point Detection: Reads package.json fields (main, module, types, exports, bin) to determine build targets
Source Mapping: Maps distribution paths (e.g., ./dist/) to source paths (e.g., ./src/)
Rollup Configuration: Automatically generates Rollup configurations for each output format
Dependency Externalization: Automatically externalizes dependencies based on package.json dependency types
Multi-Format Output: Generates ESM, CommonJS, and TypeScript declaration files as needed
Binary Patching: Adds Node.js hashbangs to executable outputs

Capabilities

CLI Interface

The main pkgroll command with comprehensive configuration options.

pkgroll [options]

# Core Options
--input, -i <paths...>          # Dist paths for source files (alternative to package.json)
--srcdist <pairs...>            # Source:distribution folder pairs (e.g., src:dist)

# Deprecated Options (use --srcdist instead)
--src <directory>               # Source directory (default: ./src) - DEPRECATED
--dist <directory>              # Distribution directory (default: ./dist) - DEPRECATED

# Build Options
--minify, -m                    # Minify output (default: false)
--target, -t <targets...>       # Target environments (default: current Node.js version)
--tsconfig, -p <path>           # Custom tsconfig.json file path

# Development Options  
--watch, -w                     # Watch mode for development (default: false)
--sourcemap [inline]            # Generate sourcemaps (optional: inline for inline maps)

# Environment & Dependencies
--env.<KEY>=<value>             # Compile-time environment variables (e.g., --env.NODE_ENV=production)
--export-condition <conditions...> # Export conditions for dependency resolution (e.g., --export-condition=node)

# Utility Options
--clean-dist                    # Clean distribution directory before build (default: false)

Configuration via package.json

pkgroll reads build configuration from your package.json:

{
  "name": "my-package",
  "type": "module",                    // Package type: "module" or "commonjs"
  
  // Output file definitions
  "main": "./dist/index.cjs",          // CommonJS entry point
  "module": "./dist/index.mjs",        // ESM entry point  
  "types": "./dist/index.d.ts",        // TypeScript declarations
  
  // Node.js export maps
  "exports": {
    "require": {
      "types": "./dist/index.d.cts",
      "default": "./dist/index.cjs"
    },
    "import": {
      "types": "./dist/index.d.mts", 
      "default": "./dist/index.mjs"
    }
  },
  
  // CLI executables (auto-patched with hashbang)
  "bin": "./dist/cli.js",
  
  // Import aliases (without # prefix supported)
  "imports": {
    "~utils": "./src/utils.js",
    "#internal": "./vendors/package/index.js"
  },
  
  // Dependency bundling control
  "dependencies": {},        // Externalized  
  "peerDependencies": {},    // Externalized
  "optionalDependencies": {},// Externalized
  "devDependencies": {}      // Bundled
}

File Extension Output Formats

pkgroll determines output format based on extensions and package.json type:

Extension	Output Format
`.cjs`	CommonJS (always)
`.mjs`	ESM (always)
`.js`	Based on `package.json#type` (default: CommonJS)
`.d.ts`	TypeScript declarations
`.d.cts`	CommonJS TypeScript declarations
`.d.mts`	ESM TypeScript declarations

Alias Configuration

Import Maps (package.json#imports)

{
  "imports": {
    // Alias without # prefix (pkgroll extension)
    "~utils": "./src/utils.js",
    "~constants": "./src/constants/index.js",
    
    // Standard Node.js subpath imports (with # prefix)
    "#internal-package": "./vendors/package/index.js"
  }
}

TypeScript Paths (tsconfig.json)

{
  "compilerOptions": {
    "paths": {
      "@foo/*": ["./src/foo/*"],
      "~bar": ["./src/bar/index.ts"]
    }
  }
}

Environment Variables

Compile-time environment variable injection:

# Single variable
pkgroll --env.NODE_ENV=production

# Multiple variables  
pkgroll --env.NODE_ENV=production --env.DEBUG=false

# Results in code replacement
process.env.NODE_ENV // becomes "production"
process.env.DEBUG    // becomes "false"

Target Environments

Specify target environments for esbuild compilation:

# Specific Node.js version
pkgroll --target=node14.18.0

# Multiple targets
pkgroll --target=es2020 --target=node16

# Browser targets
pkgroll --target=chrome90 --target=firefox88

Target also affects Node.js built-ins:

Older targets: Strips node: protocol from imports
Newer targets: Preserves node: protocol

Export Conditions

Control dependency resolution with export conditions:

# Node.js condition
pkgroll --export-condition=node

# Browser condition  
pkgroll --export-condition=browser

# Multiple conditions
pkgroll --export-condition=node --export-condition=development

Watch Mode

Development watch mode with automatic rebuilds:

# Basic watch mode
pkgroll --watch

# Watch with other options
pkgroll --watch --sourcemap --env.NODE_ENV=development

Source Maps

Generate source maps for debugging:

# External source maps
pkgroll --sourcemap

# Inline source maps  
pkgroll --sourcemap=inline

Common Usage Patterns

Library Package

{
  "name": "my-library",
  "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"
    }
  },
  "scripts": {
    "build": "pkgroll --minify --clean-dist"
  }
}

CLI Package

{
  "name": "my-cli",
  "type": "module",
  "bin": "./dist/cli.js",
  "scripts": {
    "build": "pkgroll --target=node16 --minify"
  }
}

Development Build

# Watch mode with source maps
pkgroll --watch --sourcemap --env.NODE_ENV=development

# Production build
pkgroll --minify --clean-dist --env.NODE_ENV=production