open

open is a small, focused Node.js library for launching URLs, files, and executables from a script or CLI tool. It abstracts over the platform-specific open (macOS), start (Windows), and xdg-open (Linux) commands behind a single async API, so code that needs to pop open a browser tab, an image viewer, or an arbitrary app doesn’t have to branch on process.platform itself.

Beyond the basic case, it supports waiting for the opened app to exit, passing app-specific arguments, opening a target with a specific named app (with automatic per-platform binary name detection via the bundled apps map), and opening the user’s actual default or private/incognito browser through the companion default-browser package. It uses spawn rather than exec internally, which avoids shell-injection risk when the target contains special characters.

What You Get

• A default open(target, options) export that resolves once the target app has launched, with an optional wait: true mode that resolves only after the app exits
• An openApp(name, options) export for launching a named application directly, independent of any file or URL target
• An apps object with lazily-detected, platform-correct binary names for Chrome, Firefox, Edge, Brave, and Safari, plus browser/browserPrivate shortcuts that resolve to the user’s actual default browser via default-browser
• Built-in WSL support that shells out to PowerShell (with an xdg-open fallback in sandboxed environments) and converts WSL paths to Windows paths automatically
• A bundled, up-to-date xdg-open script so Linux behavior doesn’t depend on the system having one installed

Common Use Cases

• A CLI tool that finishes a task (e.g. deploying a site or generating a report) and opens the result in the user’s browser
• A build or dev-server tool that opens http://localhost:PORT automatically when the server starts
• A desktop-adjacent Node.js script that needs to reveal a generated file (PDF, image, log) in its associated viewer app
• An authentication flow that opens a login URL in the system browser and waits for the user to complete it

Under The Hood

Architecture — The entire package is one ~420-line ESM module (index.js) built around a single internal baseOpen(options) function that all public exports funnel through. open(target, options) and openApp(name, options) are thin wrappers that normalize their arguments into a shared options object and delegate to baseOpen, which branches on process.platform (and a WSL detection flag from the wsl-utils dependency) to build the right command and cliArguments for open (macOS), PowerShell’s Start (Windows or WSL-with-PowerShell-access), or xdg-open (other platforms, using a bundled xdg-open binary co-located in the package when the system lacks one). Array-valued app options are handled recursively via a tryEachApp helper that retries each candidate app in turn and aggregates failures into an AggregateError. The final step in every branch is a single childProcess.spawn(command, cliArguments, childProcessOptions) call whose promise resolution differs by mode (wait, fallback-attempt, or fire-and-forget) via three distinct Promise constructions at the bottom of baseOpen.

Tech Stack — Plain modern JavaScript (97.6%) with a slim TypeScript layer (2.4%, index.d.ts + index.test-d.ts for type-testing via tsd); native ESM only ("type": "module"), Node.js >=20 required per engines. Runtime dependencies are all small, single-purpose Sindre Sorhus packages: default-browser and wsl-utils/powershell-utils for OS integration, define-lazy-prop for the lazily-computed apps binary map, and is-in-ssh/is-inside-container for environment detection. Dev tooling is xo (opinionated ESLint config) for linting and ava for the test runner, invoked via a single test script (xo && tsd).

Code Quality — test.js (211 lines) exercises the public API end-to-end with ava, but the file’s own header comment is candid about its limits: tests only assert that open() does not throw, since there’s ‘no way to make sure that it actually opened anything’ — verifying real app-launch behavior is left to manual testing. Naming is consistent and descriptive throughout (baseOpen, tryEachApp, fallbackAttemptSymbol), platform-specific branches are commented with rationale (e.g. why the target must come after --args on macOS, referencing GitHub issue #332), and error paths use AggregateError to preserve all per-app failures rather than only the last one.

API Design — The public surface is deliberately small: a default open() export, plus openApp() and apps named exports, all documented in a single, example-driven README. Options objects use simple boolean/string fields with sensible defaults (wait: false, background: false) rather than requiring configuration objects or setup calls, so the minimal usage (await open('https://example.com')) requires zero boilerplate. TypeScript types are shipped natively (index.d.ts) with per-option JSDoc-style comments, and the apps map removes the most common source of platform-specific friction (guessing OS-dependent binary names) from calling code.