Open URLs via Operating System

Common errors

• TypeError: openurl.open is not a function (or similar for mailto)

  cause Attempting to use `openurl` with ESM `import` syntax or incorrect CommonJS usage.
  fix Ensure you are using `require()` for CommonJS: `const openurl = require('openurl'); openurl.open('...');` If in an ESM project, consider using dynamic `import()` or, preferably, migrate to an ESM-native package like `open`.

• Error: Command failed: xdg-open: not found

  cause On Linux systems, `openurl` (or the underlying system command) relies on `xdg-open` which might not be installed or configured correctly, especially in minimal environments or WSL without proper desktop integration.
  fix Install `xdg-utils` which provides `xdg-open` on most Linux distributions (e.g., `sudo apt-get install xdg-utils` on Debian/Ubuntu, `sudo yum install xdg-utils` on Fedora/CentOS). Ensure your environment is configured to use graphical applications.

• URL with '=' does not open in Windows, opens explorer folder instead.

  cause A known, unresolved bug specific to `openurl` on Windows when the URL string contains an equals sign (`=`), causing the system to misinterpret it as a file path or command.
  fix There is no direct fix for this issue within `openurl` due to its abandonment. The recommended solution is to switch to a modern, actively maintained library like `open` (https://www.npmjs.com/package/open), which has better cross-platform handling for such edge cases.

Warnings

• breaking The `openurl` package is abandoned, with its last update over 10 years ago (v1.1.1, January 2016). It does not receive security updates, bug fixes, or compatibility improvements for newer operating systems or Node.js versions. Relying on this package in production is highly discouraged.
  Fix: Migrate to actively maintained alternatives such as the `open` package (by Sindre Sorhus) for modern, cross-platform URL opening capabilities, including ESM support and continuous maintenance. For example, `npm install open` then `import open from 'open'; await open('https://example.com');`
• gotcha This package is exclusively a CommonJS module and does not natively support ECMAScript Modules (ESM) `import` syntax. Attempting to `import openurl from 'openurl'` will result in an error in pure ESM environments.
  Fix: Ensure your project uses CommonJS `require('openurl')` or convert your project to use dynamic `import()` for `openurl` if you must use it in an ESM context, though migration to a modern ESM-compatible library is recommended.
• gotcha The package may exhibit inconsistent behavior or outright failures on certain operating systems or with specific URL formats. For instance, GitHub issues mention problems opening URLs containing `=` on Windows and unexpected side effects like wiping Firefox settings on some systems.
  Fix: Thoroughly test `openurl` functionality across all target operating systems and with various URL patterns. Due to its abandoned status, these issues are unlikely to be fixed. Prefer using a modern, actively maintained library that addresses such cross-platform nuances.

Install

• npm install openurl npm
• yarn add openurl yarn
• pnpm add openurl pnpm

Imports

• open
  wrong:

  import { open } from 'openurl';

  correct:

  const openurl = require('openurl');
  openurl.open('https://example.com');

  This package is CommonJS-only. There is no named or default ESM export. Use `require()` to access the `open` method.
• mailto
  wrong:

  import { mailto } from 'openurl';

  correct:

  const openurl = require('openurl');
  openurl.mailto(['recipient@example.com'], { subject: 'Hello', body: 'This is a test' });

  The `mailto` function is available as a property of the module loaded via `require()`. It is not an ESM export.

Quickstart

This quickstart demonstrates how to open a web URL, compose an email using a mailto link with multiple recipients, subject, and body, and open a local file path using the operating system's default applications.

const openurl = require('openurl');

// Open a URL in the default web browser
openurl.open('https://www.google.com').then(() => {
  console.log('Opened Google in browser.');
}).catch(err => {
  console.error('Failed to open URL:', err.message);
});

// Open a mailto link in the default email client with recipients, subject, and body
openurl.mailto(['john.doe@example.com', 'jane.smith@example.com'], {
    subject: 'Important Inquiry',
    body: 'Dear recipients,\n\nThis is an automatically generated email.\n\nRegards,\nYour App'
}).then(() => {
  console.log('Opened mail client for email.');
}).catch(err => {
  console.error('Failed to open mailto link:', err.message);
});

// Example of opening a local file (path should be absolute for best results)
// Note: This often opens a directory viewer on some OS if it's a directory path.
// On macOS, it might open the directory in Finder. On Windows, in Explorer.
const filePath = process.platform === 'win32' ? 'C:\\Windows' : '/tmp';
openurl.open(filePath).then(() => {
  console.log(`Opened file/directory: ${filePath}`);
}).catch(err => {
  console.error('Failed to open file/directory:', err.message);
});