0
# Browser Data and Platform Support
1

2
Browser-specific configuration, version resolution, and platform detection utilities. Provides comprehensive support for Chrome, Chromium, Firefox, Chrome Headless Shell, and ChromeDriver across multiple platforms with automatic version resolution and platform detection.
3

4
## Capabilities
5

6
### Platform Detection
7

8
Automatic detection of the current operating system and architecture combination for browser compatibility.
9

10
```typescript { .api }
11
/**
12
 * Detects current browser platform based on OS and architecture
13
 * @returns BrowserPlatform enum value or undefined for unsupported platforms
14
 */
15
function detectBrowserPlatform(): BrowserPlatform | undefined;
16

17
enum BrowserPlatform {
18
  LINUX = 'linux',
19
  LINUX_ARM = 'linux_arm',
20
  MAC = 'mac',
21
  MAC_ARM = 'mac_arm',
22
  WIN32 = 'win32',
23
  WIN64 = 'win64'
24
}
25
```
26

27
**Usage Examples:**
28

29
```typescript
30
import { detectBrowserPlatform, BrowserPlatform } from "@puppeteer/browsers";
31

32
// Detect current platform
33
const platform = detectBrowserPlatform();
34

35
if (platform) {
36
  console.log("Detected platform:", platform);
37
  
38
  switch (platform) {
39
    case BrowserPlatform.LINUX:
40
      console.log("Running on Linux x64");
41
      break;
42
    case BrowserPlatform.LINUX_ARM:
43
      console.log("Running on Linux ARM64");
44
      break;
45
    case BrowserPlatform.MAC:
46
      console.log("Running on macOS Intel");
47
      break;
48
    case BrowserPlatform.MAC_ARM:
49
      console.log("Running on macOS Apple Silicon");
50
      break;
51
    case BrowserPlatform.WIN32:
52
      console.log("Running on Windows 32-bit");
53
      break;
54
    case BrowserPlatform.WIN64:
55
      console.log("Running on Windows 64-bit");
56
      break;
57
  }
58
} else {
59
  console.error("Unsupported platform");
60
}
61
```
62

63
### Browser Support
64

65
Comprehensive support for multiple browser types with specialized handling for each browser's unique characteristics.
66

67
```typescript { .api }
68
/**
69
 * Supported browser types
70
 */
71
enum Browser {
72
  CHROME = 'chrome',
73
  CHROMEHEADLESSSHELL = 'chrome-headless-shell',
74
  CHROMIUM = 'chromium',
75
  FIREFOX = 'firefox',
76
  CHROMEDRIVER = 'chromedriver'
77
}
78
```
79

80
**Browser Characteristics:**
81

82
- **Chrome**: Chrome for Testing binaries with stable/dev/canary/beta channels
83
- **Chromium**: Snapshot builds from Chromium tip-of-tree
84
- **Firefox**: Mozilla Firefox with stable/nightly/beta/devedition/esr channels
85
- **Chrome Headless Shell**: Headless Chrome optimized for automation
86
- **ChromeDriver**: WebDriver implementation for Chrome automation
87

88
### Version Resolution
89

90
Resolve browser build IDs from release channels, tags, or version specifications.
91

92
```typescript { .api }
93
/**
94
 * Resolves build ID for browser based on platform and tag/channel
95
 * @param browser - Target browser type
96
 * @param platform - Target platform
97
 * @param tag - Release tag, channel, or specific version
98
 * @returns Promise resolving to build ID string
99
 */
100
function resolveBuildId(
101
  browser: Browser, 
102
  platform: BrowserPlatform, 
103
  tag: string | BrowserTag
104
): Promise<string>;
105

106
enum BrowserTag {
107
  CANARY = 'canary',
108
  NIGHTLY = 'nightly',
109
  BETA = 'beta',
110
  DEV = 'dev',
111
  DEVEDITION = 'devedition',
112
  STABLE = 'stable',
113
  ESR = 'esr',
114
  LATEST = 'latest'
115
}
116

117
enum ChromeReleaseChannel {
118
  STABLE = 'stable',
119
  DEV = 'dev',
120
  CANARY = 'canary',
121
  BETA = 'beta'
122
}
123
```
124

125
**Usage Examples:**
126

127
```typescript
128
import { 
129
  resolveBuildId, 
130
  Browser, 
131
  BrowserPlatform, 
132
  BrowserTag,
133
  ChromeReleaseChannel 
134
} from "@puppeteer/browsers";
135

136
// Resolve Chrome stable version
137
const chromeStable = await resolveBuildId(
138
  Browser.CHROME,
139
  BrowserPlatform.LINUX,
140
  BrowserTag.STABLE
141
);
142
console.log("Chrome stable build ID:", chromeStable);
143

144
// Resolve specific Chrome channel
145
const chromeBeta = await resolveBuildId(
146
  Browser.CHROME,
147
  BrowserPlatform.MAC,
148
  ChromeReleaseChannel.BETA
149
);
150
console.log("Chrome beta build ID:", chromeBeta);
151

152
// Resolve Firefox nightly
153
const firefoxNightly = await resolveBuildId(
154
  Browser.FIREFOX,
155
  BrowserPlatform.WIN64,
156
  BrowserTag.NIGHTLY
157
);
158
console.log("Firefox nightly build ID:", firefoxNightly);
159

160
// Resolve Chromium snapshot
161
const chromiumBuild = await resolveBuildId(
162
  Browser.CHROMIUM,
163
  BrowserPlatform.LINUX,
164
  "latest"
165
);
166
console.log("Chromium build ID:", chromiumBuild);
167
```
168

169
### Version Comparison
170

171
Get version comparator functions for sorting browser versions according to each browser's versioning scheme.
172

173
```typescript { .api }
174
/**
175
 * Returns version comparator for browser that can sort versions
176
 * @param browser - Browser type
177
 * @returns Comparison function (-1, 0, 1) for sorting
178
 */
179
function getVersionComparator(browser: Browser): (a: string, b: string) => number;
180
```
181

182
**Usage Examples:**
183

184
```typescript
185
import { getVersionComparator, Browser } from "@puppeteer/browsers";
186

187
// Sort Chrome versions
188
const chromeVersions = ["118.0.5993.70", "119.0.6045.105", "117.0.5938.149"];
189
const chromeComparator = getVersionComparator(Browser.CHROME);
190

191
chromeVersions.sort(chromeComparator);
192
console.log("Sorted Chrome versions:", chromeVersions);
193

194
// Sort Firefox versions
195
const firefoxVersions = ["119.0", "118.0.1", "119.0.1"];
196
const firefoxComparator = getVersionComparator(Browser.FIREFOX);
197

198
firefoxVersions.sort(firefoxComparator);
199
console.log("Sorted Firefox versions:", firefoxVersions);
200

201
// Find latest version
202
const versions = ["118.0.5993.70", "119.0.6045.105", "117.0.5938.149"];
203
const comparator = getVersionComparator(Browser.CHROME);
204
const latest = versions.sort(comparator).pop();
205
console.log("Latest version:", latest);
206
```
207

208
### Profile Management
209

210
Create and configure browser profiles for customized browser behavior.
211

212
```typescript { .api }
213
/**
214
 * Creates browser profile with specified options
215
 * @param browser - Target browser type
216
 * @param opts - Profile configuration options
217
 * @returns Promise resolving when profile is created
218
 */
219
function createProfile(browser: Browser, opts: ProfileOptions): Promise<void>;
220

221
interface ProfileOptions {
222
  /** Browser preferences and settings */
223
  preferences: Record<string, unknown>;
224
  /** Path to profile directory */
225
  path: string;
226
}
227
```
228

229
**Usage Examples:**
230

231
```typescript
232
import { createProfile, Browser } from "@puppeteer/browsers";
233

234
// Create Firefox profile with custom preferences
235
await createProfile(Browser.FIREFOX, {
236
  path: "./custom-firefox-profile",
237
  preferences: {
238
    "browser.startup.homepage": "https://example.com",
239
    "dom.webnotifications.enabled": false,
240
    "media.autoplay.default": 5,
241
    "network.cookie.cookieBehavior": 1
242
  }
243
});
244

245
// Create Chrome profile (uses Chrome preferences format)
246
await createProfile(Browser.CHROME, {
247
  path: "./custom-chrome-profile", 
248
  preferences: {
249
    "profile.default_content_setting_values.notifications": 2,
250
    "profile.default_content_settings.popups": 0,
251
    "profile.password_manager_enabled": false
252
  }
253
});
254

255
console.log("Browser profiles created successfully");
256
```
257

258
## Platform-Specific Considerations
259

260
### Linux Platform
261

262
**Chrome/Chromium Dependencies:**
263
- `libnss3`, `libatk-bridge2.0-0`, `libxcomposite1`, `libxdamage1`
264
- `libxrandr2`, `libgbm1`, `libxss1`, `libasound2`
265

266
**Firefox Dependencies:**  
267
- `libgtk-3-0`, `libdbus-glib-1-2`, `libxt6`
268

269
**Archive Formats:**
270
- Chrome/Chromium: `.zip` files
271
- Firefox: `.tar.bz2` files (requires `bzip2` utility)
272

273
### macOS Platform
274

275
**Archive Formats:**
276
- Chrome/Chromium: `.zip` files
277
- Firefox: `.dmg` files (requires `hdiutil` utility)
278

279
**Architecture Support:**
280
- Intel Macs: `BrowserPlatform.MAC`
281
- Apple Silicon: `BrowserPlatform.MAC_ARM`
282

283
### Windows Platform
284

285
**Archive Formats:**
286
- Chrome/Chromium: `.zip` files
287
- Firefox: `.zip` files
288

289
**Architecture Support:**
290
- 32-bit: `BrowserPlatform.WIN32`
291
- 64-bit: `BrowserPlatform.WIN64`
292

293
## Browser-Specific Features
294

295
### Chrome for Testing
296

297
Chrome for Testing provides stable, versioned Chrome binaries specifically designed for testing and automation.
298

299
```typescript
300
import { 
301
  resolveBuildId, 
302
  Browser, 
303
  BrowserPlatform,
304
  ChromeReleaseChannel 
305
} from "@puppeteer/browsers";
306

307
// Get Chrome for Testing versions
308
const stableChrome = await resolveBuildId(
309
  Browser.CHROME,
310
  BrowserPlatform.LINUX,
311
  ChromeReleaseChannel.STABLE
312
);
313

314
const canaryChrome = await resolveBuildId(
315
  Browser.CHROME,
316
  BrowserPlatform.LINUX,
317
  ChromeReleaseChannel.CANARY
318
);
319

320
console.log("Stable Chrome:", stableChrome);
321
console.log("Canary Chrome:", canaryChrome);
322
```
323

324
### Firefox Release Channels
325

326
Firefox supports multiple release channels with different update frequencies and feature sets.
327

328
```typescript
329
import { resolveBuildId, Browser, BrowserPlatform } from "@puppeteer/browsers";
330

331
// Firefox release channels
332
const channels = ['stable', 'beta', 'nightly', 'devedition', 'esr'];
333

334
for (const channel of channels) {
335
  try {
336
    const buildId = await resolveBuildId(
337
      Browser.FIREFOX,
338
      BrowserPlatform.LINUX,
339
      channel
340
    );
341
    console.log(`Firefox ${channel}:`, buildId);
342
  } catch (error) {
343
    console.error(`${channel} not available:`, error.message);
344
  }
345
}
346
```
347

348
### Chromium Snapshots
349

350
Chromium provides snapshot builds from the tip-of-tree development branch.
351

352
```typescript
353
import { resolveBuildId, Browser, BrowserPlatform } from "@puppeteer/browsers";
354

355
// Get latest Chromium snapshot
356
const chromiumSnapshot = await resolveBuildId(
357
  Browser.CHROMIUM,
358
  BrowserPlatform.LINUX,
359
  "latest"
360
);
361

362
console.log("Latest Chromium snapshot:", chromiumSnapshot);
363
```
364

365
### ChromeDriver Compatibility
366

367
ChromeDriver versions correspond to Chrome versions for compatibility.
368

369
```typescript
370
import { resolveBuildId, Browser, BrowserPlatform } from "@puppeteer/browsers";
371

372
// Get matching ChromeDriver for Chrome version
373
const chromeVersion = "118.0.5993.70";
374
const chromedriverVersion = await resolveBuildId(
375
  Browser.CHROMEDRIVER,
376
  BrowserPlatform.LINUX,
377
  chromeVersion
378
);
379

380
console.log("Chrome version:", chromeVersion);
381
console.log("ChromeDriver version:", chromedriverVersion);
382
```
383

384
## Advanced Usage Patterns
385

386
### Multi-Platform Support
387

388
Handle different platforms gracefully in cross-platform applications.
389

390
```typescript
391
import { 
392
  detectBrowserPlatform,
393
  resolveBuildId,
394
  Browser,
395
  BrowserPlatform 
396
} from "@puppeteer/browsers";
397

398
async function getBrowserForCurrentPlatform() {
399
  const platform = detectBrowserPlatform();
400
  
401
  if (!platform) {
402
    throw new Error("Unsupported platform");
403
  }
404
  
405
  // Get appropriate browser version for platform
406
  const buildId = await resolveBuildId(
407
    Browser.CHROME,
408
    platform,
409
    "stable"
410
  );
411
  
412
  return { browser: Browser.CHROME, platform, buildId };
413
}
414

415
const browserSpec = await getBrowserForCurrentPlatform();
416
console.log("Browser specification:", browserSpec);
417
```
418

419
### Version Range Resolution
420

421
Find compatible browser versions within specified ranges.
422

423
```typescript
424
import { getVersionComparator, Browser } from "@puppeteer/browsers";
425

426
function findVersionsInRange(
427
  versions: string[],
428
  browser: Browser,
429
  minVersion: string,
430
  maxVersion: string
431
): string[] {
432
  const comparator = getVersionComparator(browser);
433
  
434
  return versions.filter(version => {
435
    return comparator(version, minVersion) >= 0 && 
436
           comparator(version, maxVersion) <= 0;
437
  }).sort(comparator);
438
}
439

440
const chromeVersions = [
441
  "117.0.5938.149",
442
  "118.0.5993.70", 
443
  "119.0.6045.105",
444
  "120.0.6099.0"
445
];
446

447
const compatibleVersions = findVersionsInRange(
448
  chromeVersions,
449
  Browser.CHROME,
450
  "118.0.0.0",
451
  "119.999.999.999"
452
);
453

454
console.log("Compatible versions:", compatibleVersions);
455
```
456

457
### Fallback Browser Selection
458

459
Implement fallback logic for browser availability.
460

461
```typescript
462
import { 
463
  resolveBuildId,
464
  Browser,
465
  BrowserPlatform,
466
  ChromeReleaseChannel 
467
} from "@puppeteer/browsers";
468

469
async function getAvailableBrowser(platform: BrowserPlatform) {
470
  const browsers = [
471
    { browser: Browser.CHROME, channel: ChromeReleaseChannel.STABLE },
472
    { browser: Browser.CHROME, channel: ChromeReleaseChannel.BETA },
473
    { browser: Browser.CHROMIUM, channel: "latest" },
474
    { browser: Browser.FIREFOX, channel: "stable" }
475
  ];
476
  
477
  for (const spec of browsers) {
478
    try {
479
      const buildId = await resolveBuildId(
480
        spec.browser,
481
        platform,
482
        spec.channel
483
      );
484
      
485
      return { 
486
        browser: spec.browser, 
487
        buildId, 
488
        channel: spec.channel 
489
      };
490
    } catch (error) {
491
      console.log(`${spec.browser}@${spec.channel} not available`);
492
    }
493
  }
494
  
495
  throw new Error("No browsers available for platform");
496
}
497

498
const platform = detectBrowserPlatform();
499
if (platform) {
500
  const availableBrowser = await getAvailableBrowser(platform);
501
  console.log("Selected browser:", availableBrowser);
502
}
503
```