{"id":12308,"library":"universal-user-agent","title":"Universal User Agent String","description":"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.","status":"active","version":"7.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/gr2m/universal-user-agent","tags":["javascript","typescript"],"install":[{"cmd":"npm install universal-user-agent","lang":"bash","label":"npm"},{"cmd":"yarn add universal-user-agent","lang":"bash","label":"yarn"},{"cmd":"pnpm add universal-user-agent","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v7.0.0, this package is pure ESM and uses named exports. Default imports will not work.","wrong":"import getUserAgent from 'universal-user-agent';","symbol":"getUserAgent","correct":"import { getUserAgent } from 'universal-user-agent';"},{"note":"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().","wrong":"const getUserAgent = require('universal-user-agent');","symbol":"getUserAgent (CommonJS)","correct":"const { getUserAgent } = require('universal-user-agent');"},{"note":"The package ships with TypeScript types, allowing for proper type inference and checking.","symbol":"Type definition","correct":"import type { getUserAgent } from 'universal-user-agent';"}],"quickstart":{"code":"import { getUserAgent } from 'universal-user-agent';\n\nfunction logUserAgent() {\n  const userAgent = getUserAgent();\n  console.log('Detected User Agent:', userAgent);\n\n  if (userAgent.includes('Node.js')) {\n    console.log('Running in Node.js environment.');\n    console.log('Node.js Version:', process.version);\n  } else if (typeof navigator !== 'undefined' && navigator.userAgent) {\n    console.log('Running in Browser environment.');\n    console.log('Browser User Agent string:', navigator.userAgent);\n  } else {\n    console.log('Environment undetectable or highly minimalist.');\n  }\n}\n\nlogUserAgent();","lang":"typescript","description":"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)."},"warnings":[{"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');`","message":"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).","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Ensure your Node.js runtime is version 12 or newer. Update your development and production environments accordingly.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"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)'.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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\")`.","message":"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.","severity":"breaking","affected_versions":">=4.0.0 <7.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For CommonJS (pre-v7), use `const { getUserAgent } = require('universal-user-agent');`. For ESM (v7+), use `import { getUserAgent } from 'universal-user-agent';`.","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.","error":"TypeError: universal-user-agent is not a function"},{"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');`).","cause":"Trying to `require()` the `universal-user-agent` package in a CommonJS module when using version 7.0.0 or later.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... universal-user-agent/index.js from ... not supported."},{"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 */ }`.","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.","error":"ReferenceError: process is not defined"}],"ecosystem":"npm"}