Universal User Agent String

7.0.3 · active · verified Sun Apr 19

universal-user-agent is a JavaScript library designed to retrieve a user agent string consistently across various runtime environments, including browsers and Node.js. It is currently stable at version 7.0.3 and maintains an irregular release cadence, primarily driven by bug fixes and necessary environment compatibility updates. Its key differentiator is its ability to abstract away environment-specific logic, providing a unified `getUserAgent` function. This makes it particularly useful for libraries and applications that need to report consistent user agent information regardless of where they are executed, for purposes such as API logging, telemetry, or feature detection.

Common errors

```
TypeError: universal-user-agent is not a function
```
cause Attempting to use `require('universal-user-agent')` as a function in CommonJS after v4.0.0 or attempting to use a default import in ESM after v7.0.0.

fix For CommonJS (pre-v7), use `const { getUserAgent } = require('universal-user-agent');`. For ESM (v7+), use `import { getUserAgent } from 'universal-user-agent';`.
```
Error [ERR_REQUIRE_ESM]: require() of ES Module ... universal-user-agent/index.js from ... not supported.
```
cause Trying to `require()` the `universal-user-agent` package in a CommonJS module when using version 7.0.0 or later.

fix This package is pure ESM since v7.0.0. Convert your project to use ES Modules or use dynamic `import()` within your CommonJS module (e.g., `const { getUserAgent } = await import('universal-user-agent');`).
```
ReferenceError: process is not defined
```
cause Attempting to access `process` global in a browser environment without proper polyfills or environment checks, typically when debugging Node-specific code in a browser context.

fix Ensure your code handles different environments gracefully. The `universal-user-agent` library itself is designed to work in both, but if your application logic directly uses Node-specific globals, guard them with checks like `if (typeof process !== 'undefined') { /* Node.js specific code */ }`.

Warnings

breaking Starting with v7.0.0, `universal-user-agent` is a pure ES Module (ESM). This means it can no longer be directly `require()`d in CommonJS environments without specific tooling or configuration (e.g., dynamic import or transpilation).
Fix: Migrate your project to use ES Modules, or use dynamic `import()` if you must use it within a CommonJS module. For example: `const { getUserAgent } = await import('universal-user-agent');`
breaking Version 7.0.0 also raised the minimum Node.js requirement to Node.js 12 and higher. Older Node.js versions are no longer officially supported or tested.
Fix: Ensure your Node.js runtime is version 12 or newer. Update your development and production environments accordingly.
breaking In v6.0.0, the format of the user agent string in Node.js environments changed. It no longer uses `os-name` and consequently removes the platform release version from the string (e.g., 'Linux 4.15'). The user agent now appears simpler, like 'Node.js/10.21.0 (macOS; x64)'.
Fix: Update any parsing logic or regular expressions that relied on the detailed OS name and version previously included in the Node.js user agent string.
breaking Prior to v5.0.0, `getUserAgent()` would throw an error if it couldn't determine the user agent string. Starting with v5.0.0, it now falls back to returning the string `<environment undetectable>` instead.
Fix: Review any error handling logic that expected `getUserAgent()` to throw. Instead, check for the specific fallback string `<environment undetectable>` if you need to identify scenarios where the user agent could not be determined.
breaking Version 4.0.0 changed the CommonJS import style from a default export to a named export. `require('universal-user-agent')` no longer directly returns the `getUserAgent` function.
Fix: If using CommonJS (before v7's ESM-only change), update your imports from `const getUserAgent = require("universal-user-agent")` to `const { getUserAgent } = require("universal-user-agent")`.

Install

npm install universal-user-agent npm
yarn add universal-user-agent yarn
pnpm add universal-user-agent pnpm

Imports

getUserAgent
wrong:
```
import getUserAgent from 'universal-user-agent';
```
correct:
```
import { getUserAgent } from 'universal-user-agent';
```
Since v7.0.0, this package is pure ESM and uses named exports. Default imports will not work.
getUserAgent (CommonJS)
wrong:
```
const getUserAgent = require('universal-user-agent');
```
correct:
```
const { getUserAgent } = require('universal-user-agent');
```
For CommonJS environments, a named export (`{ getUserAgent }`) is required since v4.0.0. However, v7.0.0 made the package pure ESM, meaning direct `require` is generally not supported in modern Node.js module setups without transpilation or dynamic import().
Type definition
```
import type { getUserAgent } from 'universal-user-agent';
```
The package ships with TypeScript types, allowing for proper type inference and checking.

Quickstart

This quickstart demonstrates how to import and use `getUserAgent` to log the detected user agent string and infer the runtime environment (browser or Node.js).

import { getUserAgent } from 'universal-user-agent';

function logUserAgent() {
  const userAgent = getUserAgent();
  console.log('Detected User Agent:', userAgent);

  if (userAgent.includes('Node.js')) {
    console.log('Running in Node.js environment.');
    console.log('Node.js Version:', process.version);
  } else if (typeof navigator !== 'undefined' && navigator.userAgent) {
    console.log('Running in Browser environment.');
    console.log('Browser User Agent string:', navigator.userAgent);
  } else {
    console.log('Environment undetectable or highly minimalist.');
  }
}

logUserAgent();

view raw JSON →