browser-finder

Browser Finder

A cross-platform browser path finder that helps you locate installed browsers on Windows, macOS, and Linux.

Features

• 🔍 Cross-platform support - Works on Windows, macOS, and Linux
• 🌐 Multiple browsers - Supports Chrome, Edge, and Firefox
• 🔄 Automatic fallback - Finds any available browser when specific one isn't found
• 📝 Built-in logging - Comprehensive logging with customizable logger
• ⚡ Fast detection - Optimized for quick browser detection without expensive operations
• 🛡️ Type-safe - Written in TypeScript with full type definitions

Installation

npm install @agent-infra/browser-finder

Usage

Basic Usage

import { BrowserFinder } from '@agent-infra/browser-finder';

const finder = new BrowserFinder();

// Find any available browser (tries Chrome -> Edge -> Firefox)
const browser = finder.findBrowser();
console.log(browser.path); // "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
console.log(browser.type); // "chrome"

Find Specific Browser

import { BrowserFinder } from '@agent-infra/browser-finder';

const finder = new BrowserFinder();

// Find Chrome specifically
const chrome = finder.findBrowser('chrome');

// Find Edge specifically
const edge = finder.findBrowser('edge');

// Find Firefox specifically
const firefox = finder.findBrowser('firefox');

Custom Logger

import { BrowserFinder } from '@agent-infra/browser-finder';

const customLogger = {
  info: (msg: string, ...args: any[]) => console.log(`INFO: \${msg}`, ...args),
  warn: (msg: string, ...args: any[]) => console.warn(`WARN: \${msg}`, ...args),
  error: (msg: string, ...args: any[]) =>
    console.error(`ERROR: \${msg}`, ...args),
  // ... other logger methods
};

const finder = new BrowserFinder(customLogger);
const browser = finder.findBrowser();

API Reference

BrowserFinder

Constructor

new BrowserFinder(logger?: Logger)

• logger (optional): Custom logger instance. If not provided, uses the default logger.

Methods

findBrowser(name?: BrowserType)

Finds a browser and returns its path and type.

Parameters:

• name (optional): Specific browser to find ('chrome' | 'edge' | 'firefox')

Returns:

{
  path: string; // Full path to browser executable
  type: BrowserType; // Browser type ('chrome' | 'edge' | 'firefox')
}

Examples:

// Find any browser (automatic fallback)
const anyBrowser = finder.findBrowser();

// Find specific browser
const chrome = finder.findBrowser('chrome');
const edge = finder.findBrowser('edge');
const firefox = finder.findBrowser('firefox');

Supported Browsers

Chrome

• Windows: Chrome, Chrome Beta, Chrome Dev, Chrome Canary
• macOS: Google Chrome, Google Chrome Beta, Google Chrome Dev, Google Chrome Canary
• Linux: google-chrome-stable, google-chrome, google-chrome-beta, google-chrome-dev, chromium-browser, chromium

Edge

• Windows: Edge, Edge Beta, Edge Dev, Edge Canary
• macOS: Edge, Edge Beta, Edge Dev, Edge Canary
• Linux: microsoft-edge-stable, microsoft-edge-beta, microsoft-edge-dev

Firefox

• Windows: Mozilla Firefox, Firefox Developer Edition, Firefox Nightly
• macOS: Firefox, Firefox Developer Edition, Firefox Nightly
• Linux: firefox (all editions use same binary name)

Error Handling

The library throws descriptive errors when browsers cannot be found:

try {
  const browser = finder.findBrowser('chrome');
} catch (error) {
  if (error.name === 'ChromePathsError') {
    console.log('Chrome not found on this system');
  }
}

Error Types

• ChromePathsError - Chrome browser not found
• EdgePathsError - Edge browser not found (from edge-paths package)
• FirefoxPathsError - Firefox browser not found
• BrowserPathsError - No browser found when using automatic detection

Platform Support

• Windows (win32) - ✅ Supported
• macOS (darwin) - ✅ Supported
• Linux - ✅ Supported
• Other platforms - ❌ Will throw "Unsupported platform" error

Performance Notes

This library is optimized for fast browser detection:

• macOS: Avoids expensive lsregister -dump operations used by some other libraries
• Linux: Uses which command for quick binary lookup
• Windows: Efficiently checks common installation directories

Dependencies

• which - Cross-platform executable finder
• edge-paths - Edge browser path detection
• @agent-infra/logger - Logging functionality

License

Apache License 2.0.

Credits

Special thanks to the open source projects that inspired this toolkit:

• edge-paths - Edge browser path finder
• chrome-finder - Alternative Chrome finder
• find-chrome-bin - Another Chrome finder

Changelog

See CHANGELOG.md for release history.