chrome-launcher

chrome-launcher is a small Node.js library, maintained by the Google Chrome team, that locates an installed Chrome binary and spawns it with a fresh, disposable profile and the remote-debugging port already open. It is the launch layer underneath Lighthouse and is used throughout the Node ecosystem anywhere a script needs a real (or headless) Chrome process to attach a DevTools Protocol client to, without hand-rolling platform-specific binary discovery or profile cleanup.

Rather than trying to be a full browser-automation framework, it solves one narrow problem well: get a Chrome process running, with sane default flags for unattended environments, and hand back its port, pid, and a kill() function. Callers then drive the browser themselves via chrome-remote-interface, Puppeteer, or any other DevTools Protocol client.

What You Get

• Cross-platform Chrome/Chromium binary discovery (macOS, Linux, Windows, WSL) with priority ordering across install locations and Canary builds
• A curated set of default launch flags that disable telemetry, extensions, first-run prompts, and background throttling for clean automated runs
• Automatic, disposable user-data-dir profiles that are created fresh per launch and cleaned up on kill()
• An open remote-debugging port (or remote-debugging-pipe) handed back to you, ready for a DevTools Protocol client
• SIGINT handling that kills any launched Chrome instances when the host process is Ctrl-C’d
• A killAll() helper for tearing down every instance the module has launched in the current process

Common Use Cases

• Powering Lighthouse’s own Chrome launch step for performance and quality audits
• Spinning up headless Chrome in CI pipelines for browser-based test suites
• Bootstrapping a Chrome instance that Puppeteer, Playwright-style tooling, or a raw chrome-remote-interface client then attaches to
• Running scripted browser automation (scraping, PDF generation, screenshotting) from Node scripts and serverless functions
• Debugging by launching a visible Chrome with a known remote-debugging port for manual DevTools Protocol experimentation

Under The Hood

Architecture The module is split into four small, single-purpose files: chrome-launcher.ts owns the Launcher class and the full launch lifecycle (profile prep, flag assembly, process spawning, readiness polling, and kill/cleanup); chrome-finder.ts is a pure binary-discovery layer with one exported function per platform (darwin, darwinFast, linux, win32, wsl) that each return a priority-sorted list of installations; flags.ts is a static list of default Chrome flags with inline rationale for each one; and utils.ts centralizes cross-platform helpers plus a small hierarchy of typed LauncherError subclasses. The Launcher class is explicitly built for testability — its constructor accepts a ModuleOverrides object so fs and spawn can be swapped for stubs, which is exactly how the test suite exercises it without touching a real filesystem or process. What would break if the core abstraction changed: everything downstream (Lighthouse, chrome-remote-interface consumers) depends on the shape of the returned LaunchedChrome handle (port/pid/process/kill), so that surface is treated as a stable contract even as internals evolve.

Tech Stack Written in TypeScript targeting ES2019 with strict compiler settings (strictNullChecks, noImplicitAny, noUnusedLocals/Parameters), compiled via tsc to ESM output (“type”: “module”) with declaration files generated for consumers. Runtime dependencies are deliberately minimal: escape-string-regexp for safe path-to-regex construction during binary discovery, is-wsl for WSL detection, and lighthouse-logger for leveled logging shared with the Lighthouse project. There is no bundler or web framework involved — this is a pure Node CLI/library package built and published straight from tsc output.

Code Quality Tests live under test/ using Mocha and Sinon, with a dedicated fsMock and a stubbed spawn to simulate process launches without touching the real OS, plus separate suites for the chrome-finder logic, random-port allocation, and cross-platform utils. CI (GitHub Actions) runs the suite across multiple Node versions on Ubuntu with headful Chrome via xvfb, and separately on macOS and Windows runners, alongside a formatting check and a type-check pass — a notably thorough matrix for a package this size. Error handling is explicit and typed: a LauncherError base class with named subclasses (ChromeNotInstalledError, InvalidUserDataDirectoryError, UnsupportedPlatformError, ChromePathNotSetError) rather than generic thrown strings, and the few try/catch blocks (binary-access probing, best-effort preference-file writes) are narrowly scoped and logged rather than silently swallowed.

API Design The public surface is intentionally tiny: an async launch(opts) that resolves to {port, pid, process, kill}, a static Launcher.getInstallations()/getFirstInstallation() for binary discovery without launching anything, and a killAll() escape hatch. Every option on the Options interface has a sensible default applied through a shared defaults() helper, so a caller can go from zero configuration to a running, debuggable Chrome with a single await ChromeLauncher.launch() call, and the README backs every option with a runnable example.