0
# Configuration Options
1

2
Comprehensive configuration system supporting npm registry options, caching, security, and file system settings. All options can be passed to any pacote function or CLI command.
3

4
## Capabilities
5

6
### Core Configuration Options
7

8
Essential options that control pacote's basic behavior and are used across all package sources.
9

10
```javascript { .api }
11
interface CoreOptions {
12
  /**
13
   * Cache directory path for storing downloaded packages and metadata
14
   * @default Platform-specific cache directory (same as npm)
15
   */
16
  cache?: string;
17

18
  /**
19
   * npm registry URL for fetching packages and metadata
20
   * @default 'https://registry.npmjs.org'
21
   */
22
  registry?: string;
23

24
  /**
25
   * Expected integrity hash for package validation
26
   * Supports SRI format (sha256, sha384, sha512)
27
   */
28
  integrity?: string;
29

30
  /**
31
   * Pre-resolved package URL to skip resolution step
32
   * Useful for performance optimization when URL is already known
33
   */
34
  resolved?: string;
35

36
  /**
37
   * Base directory for resolving relative file: dependencies
38
   * @default process.cwd()
39
   */
40
  where?: string;
41
}
42
```
43

44
**Usage Examples:**
45

46
```javascript
47
const pacote = require('pacote');
48

49
// Basic configuration
50
const manifest = await pacote.manifest('express@latest', {
51
  cache: './custom-cache',
52
  registry: 'https://npm.example.com'
53
});
54

55
// With integrity verification
56
const tarball = await pacote.tarball('lodash@4.17.21', {
57
  integrity: 'sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg=='
58
});
59

60
// Using resolved URL
61
await pacote.extract('react@18.0.0', './react', {
62
  resolved: 'https://registry.npmjs.org/react/-/react-18.0.0.tgz'
63
});
64
```
65

66
### Network and Caching Options
67

68
Control how pacote interacts with the network and manages cached data.
69

70
```javascript { .api }
71
interface NetworkOptions {
72
  /**
73
   * Prefer revalidating cache entries even when not strictly necessary
74
   * @default false
75
   */
76
  preferOnline?: boolean;
77

78
  /**
79
   * Prefer using cached data when available
80
   * @default false
81
   */
82
  preferOffline?: boolean;
83

84
  /**
85
   * Only use cached data, never make network requests
86
   * @default false
87
   */
88
  offline?: boolean;
89

90
  /**
91
   * Custom packument cache Map to avoid duplicate registry requests
92
   * Only applies to registry fetchers
93
   */
94
  packumentCache?: Map<string, any>;
95

96
  /**
97
   * Registry hostname replacement behavior
98
   * 'never', 'always', or specific hostname
99
   * @default 'registry.npmjs.org'
100
   */
101
  replaceRegistryHost?: string;
102
}
103
```
104

105
**Usage Examples:**
106

107
```javascript
108
const pacote = require('pacote');
109

110
// Offline-first approach
111
const manifest = await pacote.manifest('express@4.18.2', {
112
  preferOffline: true
113
});
114

115
// Shared packument cache for performance
116
const cache = new Map();
117
const express = await pacote.packument('express', { packumentCache: cache });
118
const lodash = await pacote.packument('lodash', { packumentCache: cache });
119

120
// Registry host replacement
121
await pacote.resolve('lodash@latest', {
122
  registry: 'https://internal-registry.company.com',
123
  replaceRegistryHost: 'registry.npmjs.org'
124
});
125
```
126

127
### Security and Verification Options
128

129
Options for package integrity verification, signature validation, and attestation checking.
130

131
```javascript { .api }
132
interface SecurityOptions {
133
  /**
134
   * Enable registry signature verification for manifests
135
   * Requires configured _keys for the registry
136
   * @default false
137
   */
138
  verifySignatures?: boolean;
139

140
  /**
141
   * Enable package attestation verification via Sigstore
142
   * Requires configured _keys for the registry
143
   * @default false
144
   */
145
  verifyAttestations?: boolean;
146

147
  /**
148
   * Default integrity algorithm for packages without explicit integrity
149
   * @default 'sha512'
150
   */
151
  defaultIntegrityAlgorithm?: string;
152

153
  /**
154
   * TUF cache directory for attestation key material
155
   * @default Platform-specific cache directory
156
   */
157
  tufCache?: string;
158
}
159
```
160

161
**Usage Examples:**
162

163
```javascript
164
const pacote = require('pacote');
165

166
// With signature verification
167
const manifest = await pacote.manifest('express@latest', {
168
  verifySignatures: true,
169
  'registry.npmjs.org:_keys': ['key1', 'key2'] // Registry keys
170
});
171

172
// With attestation verification
173
await pacote.extract('lodash@4.17.21', './lodash', {
174
  verifyAttestations: true,
175
  tufCache: './custom-tuf-cache'
176
});
177

178
// Custom integrity algorithm
179
const resolved = await pacote.resolve('react@18.0.0', {
180
  defaultIntegrityAlgorithm: 'sha256'
181
});
182
```
183

184
### File System Options
185

186
Control file permissions and modes during package extraction.
187

188
```javascript { .api }
189
interface FileSystemOptions {
190
  /**
191
   * Minimum permission mode for extracted files
192
   * @default 0o666
193
   */
194
  fmode?: number;
195

196
  /**
197
   * Minimum permission mode for extracted directories
198
   * @default 0o777
199
   */
200
  dmode?: number;
201

202
  /**
203
   * Permission mode mask for extracted files and directories
204
   * @default 0o22
205
   */
206
  umask?: number;
207

208
  /**
209
   * Allow git ignore files to be processed during git operations
210
   * @default false
211
   */
212
  allowGitIgnore?: boolean;
213
}
214
```
215

216
**Usage Examples:**
217

218
```javascript
219
const pacote = require('pacote');
220

221
// Custom file permissions
222
await pacote.extract('express@4.18.2', './express', {
223
  fmode: 0o644,   // Files: -rw-r--r--
224
  dmode: 0o755,   // Directories: drwxr-xr-x
225
  umask: 0o022    // Standard umask
226
});
227

228
// More restrictive permissions
229
await pacote.extract('private-package@1.0.0', './private', {
230
  fmode: 0o600,   // Files: -rw-------
231
  dmode: 0o700,   // Directories: drwx------
232
  umask: 0o077    // Restrictive umask
233
});
234
```
235

236
### Metadata and Packaging Options
237

238
Control how package metadata is fetched and processed.
239

240
```javascript { .api }
241
interface MetadataOptions {
242
  /**
243
   * Fetch full metadata from registry instead of compressed format
244
   * Required for publish time information and extended metadata
245
   * @default false (true when 'before' is set)
246
   */
247
  fullMetadata?: boolean;
248

249
  /**
250
   * Use slower read-package-json instead of read-package-json-fast
251
   * Includes extra fields like "readme" in manifest
252
   * @default false
253
   */
254
  fullReadJson?: boolean;
255

256
  /**
257
   * Only consider packages published before this date
258
   * ISO 8601 date string, forces fullMetadata to true
259
   */
260
  before?: string;
261

262
  /**
263
   * Default dist-tag to use when choosing manifest from packument
264
   * @default 'latest'
265
   */
266
  defaultTag?: string;
267
}
268
```
269

270
**Usage Examples:**
271

272
```javascript
273
const pacote = require('pacote');
274

275
// Full metadata with publish times
276
const packument = await pacote.packument('express', {
277
  fullMetadata: true
278
});
279
console.log('Publish times:', packument.time);
280

281
// Only versions before specific date
282
const oldManifest = await pacote.manifest('lodash@*', {
283
  before: '2020-01-01T00:00:00.000Z'
284
});
285

286
// Custom default tag
287
const betaManifest = await pacote.manifest('react', {
288
  defaultTag: 'beta'
289
});
290

291
// Full readme in manifest
292
const withReadme = await pacote.manifest('express@latest', {
293
  fullReadJson: true
294
});
295
console.log('Readme:', withReadme.readme);
296
```
297

298
### Build and Execution Options
299

300
Options for executing prepare scripts and managing dependencies during packaging.
301

302
```javascript { .api }
303
interface BuildOptions {
304
  /**
305
   * npm binary path for running prepare scripts
306
   * @default 'npm'
307
   */
308
  npmBin?: string;
309

310
  /**
311
   * npm install command array for dependency installation
312
   * @default ['install', '--force']
313
   */
314
  npmInstallCmd?: string[];
315

316
  /**
317
   * npm CLI configuration array
318
   */
319
  npmCliConfig?: string[];
320

321
  /**
322
   * Arborist constructor for dependency tree operations
323
   * Required for DirFetcher operations
324
   */
325
  Arborist?: typeof import('@npmcli/arborist');
326

327
  /**
328
   * Pre-built Arborist tree object
329
   */
330
  tree?: Object;
331

332
  /**
333
   * Environment variables for prepare script execution
334
   */
335
  env?: Record<string, string>;
336

337
  /**
338
   * Shell for running scripts
339
   * @default '/bin/sh'
340
   */
341
  scriptShell?: string;
342

343
  /**
344
   * Run scripts with inherit stdio (foreground)
345
   * @default false
346
   */
347
  foregroundScripts?: boolean;
348

349
  /**
350
   * Skip running prepare scripts
351
   * @default false
352
   */
353
  ignoreScripts?: boolean;
354

355
  /**
356
   * Workspace configuration for packlist
357
   */
358
  workspaces?: string[] | boolean;
359
}
360
```
361

362
**Usage Examples:**
363

364
```javascript
365
const pacote = require('pacote');
366
const Arborist = require('@npmcli/arborist');
367

368
// Custom npm binary
369
await pacote.extract('file:./my-package', './built', {
370
  npmBin: 'yarn',
371
  npmInstallCmd: ['install', '--frozen-lockfile']
372
});
373

374
// With Arborist for directory operations
375
const dirFetcher = new (require('pacote').DirFetcher)('file:./src', {
376
  Arborist,
377
  env: {
378
    NODE_ENV: 'production'
379
  }
380
});
381

382
await dirFetcher.extract('./dist');
383
```
384

385
## Configuration Inheritance
386

387
Options are inherited and merged from multiple sources:
388

389
1. Default values
390
2. npm configuration files (.npmrc)
391
3. Environment variables
392
4. Passed options object
393

394
```javascript
395
const pacote = require('pacote');
396

397
// This will use:
398
// - Default registry from .npmrc or environment
399
// - Cache directory from npm config
400
// - Plus explicit options
401
const manifest = await pacote.manifest('express@latest', {
402
  preferOffline: true,  // Explicit option
403
  integrity: 'sha512-...' // Explicit option
404
  // registry: inherited from npm config
405
  // cache: inherited from npm config
406
});
407
```
408

409
## Registry-Specific Configuration
410

411
Configuration keys can be scoped to specific registries:
412

413
```javascript
414
const options = {
415
  registry: 'https://internal-registry.company.com',
416
  '//internal-registry.company.com:_authToken': 'token123',
417
  '//internal-registry.company.com:_keys': ['key1', 'key2'],
418
  
419
  // Public registry settings still available
420
  '//registry.npmjs.org:_keys': ['public-key1']
421
};
422

423
const manifest = await pacote.manifest('@company/private-pkg@latest', options);
424
```
425

426
## Error Handling with Configuration
427

428
Different configuration options can affect error behavior:
429

430
```javascript
431
const pacote = require('pacote');
432

433
try {
434
  // This might fail with network error
435
  await pacote.manifest('express@latest', { preferOnline: true });
436
} catch (error) {
437
  if (error.code === 'ENOTFOUND') {
438
    // Fallback to offline
439
    const manifest = await pacote.manifest('express@latest', { 
440
      offline: true 
441
    });
442
  }
443
}
444

445
try {
446
  // This might fail with integrity error
447
  await pacote.extract('lodash@4.17.21', './lodash', {
448
    integrity: 'sha512-wrong-hash'
449
  });
450
} catch (error) {
451
  if (error.code === 'EINTEGRITY') {
452
    console.log('Integrity verification failed');
453
    // Extract without integrity check
454
    await pacote.extract('lodash@4.17.21', './lodash');
455
  }
456
}
457
```
458

459
## Performance Optimization
460

461
Configuration options for optimal performance:
462

463
```javascript
464
const pacote = require('pacote');
465

466
// Shared cache for multiple operations
467
const cache = new Map();
468
const sharedOptions = {
469
  packumentCache: cache,
470
  preferOffline: true,
471
  fullMetadata: false // Use compressed format
472
};
473

474
// Batch operations with shared config
475
const results = await Promise.all([
476
  pacote.manifest('express@latest', sharedOptions),
477
  pacote.manifest('lodash@latest', sharedOptions),
478
  pacote.manifest('react@latest', sharedOptions)
479
]);
480

481
// Pre-resolved URLs for known packages
482
const knownPackages = {
483
  'express@4.18.2': 'https://registry.npmjs.org/express/-/express-4.18.2.tgz'
484
};
485

486
for (const [spec, resolved] of Object.entries(knownPackages)) {
487
  await pacote.extract(spec, `./packages/${spec.split('@')[0]}`, {
488
    resolved, // Skip resolution step
489
    preferOffline: true
490
  });
491
}
492
```