0
# Cache Management
1

2
Browser cache directory management with metadata handling, alias resolution, and installation tracking. Provides comprehensive control over browser storage, cleanup operations, and installation metadata.
3

4
## Capabilities
5

6
### Cache Class
7

8
Main cache management class providing directory structure management and browser installation tracking.
9

10
```typescript { .api }
11
/**
12
 * Browser cache directory management class
13
 */
14
class Cache {
15
  /** Create cache instance with specified root directory */
16
  constructor(rootDir: string);
17
  
18
  /** Get the root cache directory path */
19
  get rootDir(): string;
20
  
21
  /** Get browser-specific cache directory */
22
  browserRoot(browser: Browser): string;
23
  
24
  /** Get metadata file path for browser */
25
  metadataFile(browser: Browser): string;
26
  
27
  /** Read browser metadata from cache */
28
  readMetadata(browser: Browser): Metadata;
29
  
30
  /** Write browser metadata to cache */
31
  writeMetadata(browser: Browser, metadata: Metadata): void;
32
  
33
  /** Resolve alias to build ID */
34
  resolveAlias(browser: Browser, alias: string): string | undefined;
35
  
36
  /** Get installation directory for specific browser/platform/build */
37
  installationDir(browser: Browser, platform: BrowserPlatform, buildId: string): string;
38
  
39
  /** Remove entire cache directory */
40
  clear(): void;
41
  
42
  /** Uninstall specific browser installation */
43
  uninstall(browser: Browser, platform: BrowserPlatform, buildId: string): void;
44
  
45
  /** List all installed browsers in cache */
46
  getInstalledBrowsers(): InstalledBrowser[];
47
  
48
  /** Compute executable path for browser installation */
49
  computeExecutablePath(options: ComputeExecutablePathOptions): string;
50
}
51
```
52

53
**Usage Examples:**
54

55
```typescript
56
import { Cache, Browser, BrowserPlatform } from "@puppeteer/browsers";
57

58
// Create cache instance
59
const cache = new Cache("./browsers-cache");
60

61
// Get browser-specific information
62
const chromeRoot = cache.browserRoot(Browser.CHROME);
63
const metadataFile = cache.metadataFile(Browser.CHROME);
64

65
console.log("Chrome cache root:", chromeRoot);
66
console.log("Metadata file:", metadataFile);
67

68
// List all installed browsers
69
const installed = cache.getInstalledBrowsers();
70
installed.forEach(browser => {
71
  console.log(`${browser.browser}@${browser.buildId} (${browser.platform})`);
72
});
73

74
// Clean up cache
75
cache.clear();
76
console.log("Cache cleared");
77
```
78

79
### InstalledBrowser Class
80

81
Represents an installed browser instance with metadata and path information.
82

83
```typescript { .api }
84
/**
85
 * Represents an installed browser instance
86
 */
87
class InstalledBrowser {
88
  /** Browser type */
89
  browser: Browser;
90
  
91
  /** Build identifier */
92
  buildId: string;
93
  
94
  /** Target platform */
95
  platform: BrowserPlatform;
96
  
97
  /** Path to browser executable (readonly) */
98
  readonly executablePath: string;
99
  
100
  /** Path to installation directory */
101
  get path(): string;
102
  
103
  /** Read browser metadata from cache */
104
  readMetadata(): Metadata;
105
  
106
  /** Write browser metadata to cache */
107
  writeMetadata(metadata: Metadata): void;
108
}
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
import { install, Browser } from "@puppeteer/browsers";
115

116
// Install browser and work with InstalledBrowser instance
117
const installedBrowser = await install({
118
  cacheDir: "./browsers-cache",
119
  browser: Browser.CHROME,
120
  buildId: "118.0.5993.70",
121
  buildIdAlias: "stable"
122
});
123

124
console.log("Browser:", installedBrowser.browser);
125
console.log("Build ID:", installedBrowser.buildId);
126
console.log("Platform:", installedBrowser.platform);
127
console.log("Installation path:", installedBrowser.path);
128
console.log("Executable path:", installedBrowser.executablePath);
129

130
// Work with metadata
131
const metadata = installedBrowser.readMetadata();
132
console.log("Current aliases:", metadata.aliases);
133

134
// Add new alias
135
metadata.aliases["latest"] = installedBrowser.buildId;
136
installedBrowser.writeMetadata(metadata);
137
```
138

139
### Metadata Management
140

141
Browser metadata structure containing alias mappings and installation information.
142

143
```typescript { .api }
144
/**
145
 * Browser metadata structure
146
 */
147
interface Metadata {
148
  /** Maps aliases to build IDs (e.g., 'stable' -> '118.0.5993.70') */
149
  aliases: Record<string, string>;
150
}
151
```
152

153
**Usage Examples:**
154

155
```typescript
156
import { Cache, Browser } from "@puppeteer/browsers";
157

158
const cache = new Cache("./browsers-cache");
159

160
// Read existing metadata
161
const metadata = cache.readMetadata(Browser.CHROME);
162
console.log("Current aliases:", metadata.aliases);
163

164
// Add alias mapping
165
metadata.aliases["my-stable"] = "118.0.5993.70";
166
metadata.aliases["latest"] = "119.0.6045.105";
167

168
// Save updated metadata
169
cache.writeMetadata(Browser.CHROME, metadata);
170

171
// Resolve aliases
172
const stableVersion = cache.resolveAlias(Browser.CHROME, "my-stable");
173
const latestVersion = cache.resolveAlias(Browser.CHROME, "latest");
174

175
console.log("Stable version:", stableVersion);
176
console.log("Latest version:", latestVersion);
177
```
178

179
## Cache Directory Structure
180

181
The cache uses a structured directory layout for organizing browser installations:
182

183
```
184
cache-root/
185
├── chrome/
186
│   ├── metadata.json
187
│   ├── linux-118.0.5993.70/
188
│   │   └── chrome-linux64/
189
│   │       └── chrome
190
│   └── linux-119.0.6045.105/
191
│       └── chrome-linux64/
192
│           └── chrome
193
├── firefox/
194
│   ├── metadata.json
195
│   └── linux-119.0/
196
│       └── firefox/
197
│           └── firefox
198
└── chromium/
199
    ├── metadata.json
200
    └── linux-1097615/
201
        └── chrome-linux/
202
            └── chrome
203
```
204

205
### Directory Methods
206

207
```typescript
208
import { Cache, Browser, BrowserPlatform } from "@puppeteer/browsers";
209

210
const cache = new Cache("./browsers-cache");
211

212
// Get specific directories
213
const installDir = cache.installationDir(
214
  Browser.CHROME,
215
  BrowserPlatform.LINUX,
216
  "118.0.5993.70"
217
);
218

219
const browserRoot = cache.browserRoot(Browser.CHROME);
220
const metadataFile = cache.metadataFile(Browser.CHROME);
221

222
console.log("Installation directory:", installDir);
223
console.log("Browser root:", browserRoot);
224
console.log("Metadata file:", metadataFile);
225
```
226

227
## Alias Management
228

229
Aliases provide human-readable names for browser versions, making it easier to reference commonly used builds.
230

231
### Common Alias Patterns
232

233
- **Release Channels**: `stable`, `beta`, `dev`, `canary`
234
- **Version Tags**: `latest`, `lts`, `current`
235
- **Custom Names**: `testing`, `production`, `fallback`
236

237
```typescript
238
import { Cache, Browser } from "@puppeteer/browsers";
239

240
const cache = new Cache("./browsers-cache");
241

242
// Set up aliases for different Chrome channels
243
const metadata = cache.readMetadata(Browser.CHROME);
244
metadata.aliases = {
245
  "stable": "118.0.5993.70",
246
  "beta": "119.0.6045.105",
247
  "dev": "120.0.6099.0",
248
  "canary": "121.0.6120.0",
249
  "testing": "118.0.5993.70",
250
  "latest": "119.0.6045.105"
251
};
252

253
cache.writeMetadata(Browser.CHROME, metadata);
254

255
// Use aliases to resolve versions
256
const testingVersion = cache.resolveAlias(Browser.CHROME, "testing");
257
const latestVersion = cache.resolveAlias(Browser.CHROME, "latest");
258

259
console.log("Testing version:", testingVersion);
260
console.log("Latest version:", latestVersion);
261
```
262

263
## Cache Operations
264

265
### Installation Tracking
266

267
The cache automatically tracks all browser installations and maintains metadata about each installation.
268

269
```typescript
270
import { Cache, install, Browser } from "@puppeteer/browsers";
271

272
const cache = new Cache("./browsers-cache");
273

274
// Install multiple browser versions
275
await install({
276
  cacheDir: cache.rootDir,
277
  browser: Browser.CHROME,
278
  buildId: "118.0.5993.70",
279
  buildIdAlias: "stable"
280
});
281

282
await install({
283
  cacheDir: cache.rootDir,
284
  browser: Browser.CHROME,
285
  buildId: "119.0.6045.105",
286
  buildIdAlias: "beta"
287
});
288

289
// List all installations
290
const browsers = cache.getInstalledBrowsers();
291
console.log(`Found ${browsers.length} browser installations:`);
292

293
browsers.forEach(browser => {
294
  console.log(`  ${browser.browser}@${browser.buildId}`);
295
  console.log(`    Platform: ${browser.platform}`);
296
  console.log(`    Path: ${browser.path}`);
297
  console.log(`    Executable: ${browser.executablePath}`);
298
});
299
```
300

301
### Selective Uninstallation
302

303
Remove specific browser installations while preserving others.
304

305
```typescript
306
import { Cache, Browser, BrowserPlatform } from "@puppeteer/browsers";
307

308
const cache = new Cache("./browsers-cache");
309

310
// List installations before cleanup
311
console.log("Before cleanup:");
312
cache.getInstalledBrowsers().forEach(browser => {
313
  console.log(`  ${browser.browser}@${browser.buildId}`);
314
});
315

316
// Remove specific installation
317
cache.uninstall(Browser.CHROME, BrowserPlatform.LINUX, "118.0.5993.70");
318

319
// List installations after cleanup
320
console.log("After cleanup:");
321
cache.getInstalledBrowsers().forEach(browser => {
322
  console.log(`  ${browser.browser}@${browser.buildId}`);
323
});
324
```
325

326
### Complete Cache Cleanup
327

328
Remove all browser installations and metadata.
329

330
```typescript
331
import { Cache } from "@puppeteer/browsers";
332

333
const cache = new Cache("./browsers-cache");
334

335
console.log("Installed browsers:", cache.getInstalledBrowsers().length);
336

337
// Clear entire cache
338
cache.clear();
339

340
console.log("Cache cleared. Installed browsers:", cache.getInstalledBrowsers().length);
341
```
342

343
## Integration with Installation Functions
344

345
The Cache class integrates seamlessly with installation functions, providing automatic metadata management.
346

347
```typescript
348
import { install, getInstalledBrowsers, Browser } from "@puppeteer/browsers";
349

350
const cacheDir = "./browsers-cache";
351

352
// Install with automatic cache management
353
const browser = await install({
354
  cacheDir,
355
  browser: Browser.CHROME,
356
  buildId: "118.0.5993.70",
357
  buildIdAlias: "stable"
358
});
359

360
// Query installations using high-level functions
361
const installed = await getInstalledBrowsers({ cacheDir });
362

363
// Or use Cache class directly for advanced operations
364
import { Cache } from "@puppeteer/browsers";
365
const cache = new Cache(cacheDir);
366

367
const metadata = cache.readMetadata(Browser.CHROME);
368
console.log("Available aliases:", Object.keys(metadata.aliases));
369
```
370

371
## Error Handling
372

373
Cache operations may encounter various error conditions:
374

375
- **File System Errors**: Permission issues, disk space, path access
376
- **Metadata Corruption**: Invalid JSON, missing files
377
- **Directory Issues**: Non-existent paths, invalid structure
378

379
```typescript
380
import { Cache, Browser } from "@puppeteer/browsers";
381

382
const cache = new Cache("./browsers-cache");
383

384
try {
385
  const metadata = cache.readMetadata(Browser.CHROME);
386
  console.log("Metadata loaded successfully");
387
} catch (error) {
388
  console.error("Failed to read metadata:", error.message);
389
  
390
  // Initialize empty metadata
391
  cache.writeMetadata(Browser.CHROME, { aliases: {} });
392
}
393

394
try {
395
  cache.uninstall(Browser.CHROME, BrowserPlatform.LINUX, "nonexistent");
396
} catch (error) {
397
  console.error("Uninstall failed:", error.message);
398
}
399
```