0
# pkgroll
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: pkgroll
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Node.js Version**: >=18
10
- **TypeScript Support**: Optional peer dependency (^4.1 || ^5.0)
11
- **Installation**: `npm install --save-dev pkgroll`
12
13
## Core Imports
14
15
pkgroll is a CLI tool only - it provides no programmatic API. All functionality is accessed through the command line interface.
16
17
## Basic Usage
18
19
```bash
20
# Install as dev dependency
21
npm install --save-dev pkgroll
22
23
# Run with default configuration
24
npx pkgroll
25
26
# Or add to package.json scripts
27
{
28
"scripts": {
29
"build": "pkgroll"
30
}
31
}
32
npm run build
33
```
34
35
## Architecture
36
37
pkgroll operates by:
38
39
1. **Entry Point Detection**: Reads `package.json` fields (`main`, `module`, `types`, `exports`, `bin`) to determine build targets
40
2. **Source Mapping**: Maps distribution paths (e.g., `./dist/`) to source paths (e.g., `./src/`)
41
3. **Rollup Configuration**: Automatically generates Rollup configurations for each output format
42
4. **Dependency Externalization**: Automatically externalizes dependencies based on `package.json` dependency types
43
5. **Multi-Format Output**: Generates ESM, CommonJS, and TypeScript declaration files as needed
44
6. **Binary Patching**: Adds Node.js hashbangs to executable outputs
45
46
## Capabilities
47
48
### CLI Interface
49
50
The main pkgroll command with comprehensive configuration options.
51
52
```bash { .api }
53
pkgroll [options]
54
55
# Core Options
56
--input, -i <paths...> # Dist paths for source files (alternative to package.json)
57
--srcdist <pairs...> # Source:distribution folder pairs (e.g., src:dist)
58
59
# Deprecated Options (use --srcdist instead)
60
--src <directory> # Source directory (default: ./src) - DEPRECATED
61
--dist <directory> # Distribution directory (default: ./dist) - DEPRECATED
62
63
# Build Options
64
--minify, -m # Minify output (default: false)
65
--target, -t <targets...> # Target environments (default: current Node.js version)
66
--tsconfig, -p <path> # Custom tsconfig.json file path
67
68
# Development Options
69
--watch, -w # Watch mode for development (default: false)
70
--sourcemap [inline] # Generate sourcemaps (optional: inline for inline maps)
71
72
# Environment & Dependencies
73
--env.<KEY>=<value> # Compile-time environment variables (e.g., --env.NODE_ENV=production)
74
--export-condition <conditions...> # Export conditions for dependency resolution (e.g., --export-condition=node)
75
76
# Utility Options
77
--clean-dist # Clean distribution directory before build (default: false)
78
```
79
80
### Configuration via package.json
81
82
pkgroll reads build configuration from your `package.json`:
83
84
```json { .api }
85
{
86
"name": "my-package",
87
"type": "module", // Package type: "module" or "commonjs"
88
89
// Output file definitions
90
"main": "./dist/index.cjs", // CommonJS entry point
91
"module": "./dist/index.mjs", // ESM entry point
92
"types": "./dist/index.d.ts", // TypeScript declarations
93
94
// Node.js export maps
95
"exports": {
96
"require": {
97
"types": "./dist/index.d.cts",
98
"default": "./dist/index.cjs"
99
},
100
"import": {
101
"types": "./dist/index.d.mts",
102
"default": "./dist/index.mjs"
103
}
104
},
105
106
// CLI executables (auto-patched with hashbang)
107
"bin": "./dist/cli.js",
108
109
// Import aliases (without # prefix supported)
110
"imports": {
111
"~utils": "./src/utils.js",
112
"#internal": "./vendors/package/index.js"
113
},
114
115
// Dependency bundling control
116
"dependencies": {}, // Externalized
117
"peerDependencies": {}, // Externalized
118
"optionalDependencies": {},// Externalized
119
"devDependencies": {} // Bundled
120
}
121
```
122
123
## File Extension Output Formats
124
125
pkgroll determines output format based on extensions and package.json type:
126
127
| Extension | Output Format |
128
|-----------|---------------|
129
| `.cjs` | CommonJS (always) |
130
| `.mjs` | ESM (always) |
131
| `.js` | Based on `package.json#type` (default: CommonJS) |
132
| `.d.ts` | TypeScript declarations |
133
| `.d.cts` | CommonJS TypeScript declarations |
134
| `.d.mts` | ESM TypeScript declarations |
135
136
## Alias Configuration
137
138
### Import Maps (package.json#imports)
139
140
```json { .api }
141
{
142
"imports": {
143
// Alias without # prefix (pkgroll extension)
144
"~utils": "./src/utils.js",
145
"~constants": "./src/constants/index.js",
146
147
// Standard Node.js subpath imports (with # prefix)
148
"#internal-package": "./vendors/package/index.js"
149
}
150
}
151
```
152
153
### TypeScript Paths (tsconfig.json)
154
155
```json { .api }
156
{
157
"compilerOptions": {
158
"paths": {
159
"@foo/*": ["./src/foo/*"],
160
"~bar": ["./src/bar/index.ts"]
161
}
162
}
163
}
164
```
165
166
## Environment Variables
167
168
Compile-time environment variable injection:
169
170
```bash { .api }
171
# Single variable
172
pkgroll --env.NODE_ENV=production
173
174
# Multiple variables
175
pkgroll --env.NODE_ENV=production --env.DEBUG=false
176
177
# Results in code replacement
178
process.env.NODE_ENV // becomes "production"
179
process.env.DEBUG // becomes "false"
180
```
181
182
## Target Environments
183
184
Specify target environments for esbuild compilation:
185
186
```bash { .api }
187
# Specific Node.js version
188
pkgroll --target=node14.18.0
189
190
# Multiple targets
191
pkgroll --target=es2020 --target=node16
192
193
# Browser targets
194
pkgroll --target=chrome90 --target=firefox88
195
```
196
197
Target also affects Node.js built-ins:
198
- Older targets: Strips `node:` protocol from imports
199
- Newer targets: Preserves `node:` protocol
200
201
## Export Conditions
202
203
Control dependency resolution with export conditions:
204
205
```bash { .api }
206
# Node.js condition
207
pkgroll --export-condition=node
208
209
# Browser condition
210
pkgroll --export-condition=browser
211
212
# Multiple conditions
213
pkgroll --export-condition=node --export-condition=development
214
```
215
216
## Watch Mode
217
218
Development watch mode with automatic rebuilds:
219
220
```bash { .api }
221
# Basic watch mode
222
pkgroll --watch
223
224
# Watch with other options
225
pkgroll --watch --sourcemap --env.NODE_ENV=development
226
```
227
228
## Source Maps
229
230
Generate source maps for debugging:
231
232
```bash { .api }
233
# External source maps
234
pkgroll --sourcemap
235
236
# Inline source maps
237
pkgroll --sourcemap=inline
238
```
239
240
## Common Usage Patterns
241
242
### Library Package
243
244
```json
245
{
246
"name": "my-library",
247
"type": "module",
248
"main": "./dist/index.cjs",
249
"module": "./dist/index.mjs",
250
"types": "./dist/index.d.ts",
251
"exports": {
252
"require": {
253
"types": "./dist/index.d.cts",
254
"default": "./dist/index.cjs"
255
},
256
"import": {
257
"types": "./dist/index.d.mts",
258
"default": "./dist/index.mjs"
259
}
260
},
261
"scripts": {
262
"build": "pkgroll --minify --clean-dist"
263
}
264
}
265
```
266
267
### CLI Package
268
269
```json
270
{
271
"name": "my-cli",
272
"type": "module",
273
"bin": "./dist/cli.js",
274
"scripts": {
275
"build": "pkgroll --target=node16 --minify"
276
}
277
}
278
```
279
280
### Development Build
281
282
```bash
283
# Watch mode with source maps
284
pkgroll --watch --sourcemap --env.NODE_ENV=development
285
286
# Production build
287
pkgroll --minify --clean-dist --env.NODE_ENV=production
288
```