0
# Pacote
1

2
Pacote is a comprehensive JavaScript package downloader and fetcher that serves as the core package handling library for npm. It provides a unified API for fetching package manifests, tarballs, and metadata from various sources including the npm registry, GitHub repositories, local directories, and tarball URLs.
3

4
## Package Information
5

6
- **Package Name**: pacote
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install pacote`
10

11
## Core Imports
12

13
```javascript
14
const pacote = require('pacote');
15
```
16

17
For ESM:
18

19
```javascript
20
import * as pacote from 'pacote';
21
// or
22
import { resolve, extract, manifest, packument, tarball } from 'pacote';
23
```
24

25
## Basic Usage
26

27
```javascript
28
const pacote = require('pacote');
29

30
// Get a package manifest
31
const manifest = await pacote.manifest('lodash@latest');
32
console.log('Package version:', manifest.version);
33

34
// Extract a package to a directory
35
const result = await pacote.extract('react@18.0.0', './packages/react');
36
console.log('Extracted from:', result.from);
37

38
// Download package tarball
39
const tarballData = await pacote.tarball('express@4.18.0');
40
console.log('Tarball size:', tarballData.length, 'bytes');
41

42
// Resolve package specifier to URL
43
const resolved = await pacote.resolve('github:npm/cli');
44
console.log('Resolved URL:', resolved);
45
```
46

47
## Architecture
48

49
Pacote is built around several key components:
50

51
- **Core API Functions**: High-level functions (`resolve`, `extract`, `manifest`, `packument`, `tarball`) for common package operations
52
- **Fetcher Classes**: Specialized classes for different package sources (registry, git, file, directory, remote)
53
- **Unified Interface**: Any package specifier that npm can install works with pacote
54
- **Caching System**: Built-in caching for performance and offline support
55
- **Security Features**: Integrity verification, signature validation, and attestation support
56

57
## Capabilities
58

59
### Core Package Operations
60

61
Essential functions for fetching, extracting, and resolving packages from any source that npm supports.
62

63
```javascript { .api }
64
/**
65
 * Resolve a package specifier to a tarball URL, file path, or git repository
66
 */
67
function resolve(spec, opts);
68

69
/**
70
 * Extract a package's tarball into a destination folder
71
 */
72
function extract(spec, dest, opts);
73

74
/**
75
 * Fetch a package's manifest (package.json plus metadata)
76
 */
77
function manifest(spec, opts);
78

79
/**
80
 * Fetch a package's packument (full package document)
81
 */
82
function packument(spec, opts);
83

84
/**
85
 * Get package tarball data as a buffer
86
 */
87
function tarball(spec, opts);
88

89
/**
90
 * Stream tarball through a handler function
91
 */
92
function tarball.stream(spec, handler, opts);
93

94
/**
95
 * Save tarball to a file
96
 */
97
function tarball.file(spec, dest, opts);
98
```
99

100
[Core API Functions](./core-api.md)
101

102
### Advanced Fetcher Classes
103

104
Specialized fetcher classes for different package sources and advanced usage patterns.
105

106
```javascript { .api }
107
/**
108
 * Fetcher classes for specific package types
109
 */
110
class GitFetcher extends FetcherBase;
111
class RegistryFetcher extends FetcherBase;
112
class FileFetcher extends FetcherBase;
113
class DirFetcher extends FetcherBase;
114
class RemoteFetcher extends FetcherBase;
115

116
/**
117
 * Base fetcher class with common functionality
118
 */
119
class FetcherBase {
120
  constructor(spec, opts);
121
  resolve();
122
  manifest();
123
  packument();
124
  extract(dest);
125
  tarball();
126
  tarballStream(handler);
127
  tarballFile(dest);
128
}
129
```
130

131
[Fetcher Classes](./fetchers.md)
132

133
### Command Line Interface
134

135
Command line tool for package operations without requiring programmatic usage.
136

137
```bash { .api }
138
# Resolve package specifier
139
pacote resolve <spec> [--long]
140

141
# Fetch manifest
142
pacote manifest <spec>
143

144
# Fetch packument
145
pacote packument <spec>
146

147
# Download tarball
148
pacote tarball <spec> [filename]
149

150
# Extract package
151
pacote extract <spec> <folder>
152
```
153

154
[CLI Interface](./cli.md)
155

156
### Configuration Options
157

158
Comprehensive configuration system supporting npm registry options, caching, security, and file system settings.
159

160
```javascript { .api }
161
interface PacoteOptions {
162
  cache?: string;
163
  registry?: string;
164
  integrity?: string;
165
  resolved?: string;
166
  preferOnline?: boolean;
167
  preferOffline?: boolean;
168
  offline?: boolean;
169
  verifySignatures?: boolean;
170
  verifyAttestations?: boolean;
171
  packumentCache?: Map<string, any>;
172
  tufCache?: string;
173
  fullMetadata?: boolean;
174
  fullReadJson?: boolean;
175
  before?: string;
176
  defaultTag?: string;
177
  fmode?: number;
178
  dmode?: number;
179
  umask?: number;
180
  replaceRegistryHost?: string;
181
  // ... and many more options
182
}
183
```
184

185
[Configuration Options](./configuration.md)
186

187
### Utility Functions
188

189
Standalone utility functions for specialized package operations and processing.
190

191
```javascript { .api }
192
/**
193
 * Utility functions for package processing
194
 */
195
function addGitSha(spec, sha);
196
function cacheDir(fakePlatform);
197
function isPackageBin(pkg, path);
198
function tarCreateOptions(manifest);
199
function removeTrailingSlashes(input);
200
function npm(npmBin, npmCommand, cwd, env, extra);
201
```
202

203
[Utility Functions](./utility-functions.md)
204

205
## Types
206

207
```javascript { .api }
208
/**
209
 * Package specifier - any format that npm can install
210
 */
211
type PackageSpec = string;
212

213
/**
214
 * Extraction result with metadata
215
 */
216
interface ExtractionResult {
217
  from: string;
218
  resolved: string;
219
  integrity: string;
220
}
221

222
/**
223
 * Package manifest with metadata
224
 */
225
interface PackageManifest {
226
  name: string;
227
  version: string;
228
  _resolved: string;
229
  _from: string;
230
  _integrity: string;
231
  _id: string;
232
  // ... plus all standard package.json fields
233
}
234

235
/**
236
 * Full packument document
237
 */
238
interface Packument {
239
  name: string;
240
  versions: { [version: string]: PackageManifest };
241
  'dist-tags': { [tag: string]: string };
242
  time?: { [version: string]: string };
243
  _contentLength: number;
244
}
245

246
/**
247
 * Tarball data with metadata
248
 */
249
interface TarballResult extends Buffer {
250
  from: string;
251
  resolved: string;
252
  integrity: string;
253
}
254
```