Device Detector JS

3.0.3 · active · verified Sun Apr 19

device-detector-js is a robust JavaScript/TypeScript library designed for precise user agent parsing and device detection. It identifies the browser, operating system, device type (desktop, mobile, tablet, TV, etc.), brand, and model from any user agent string. As a JavaScript port of Matomo's highly regarded `device-detector` library (specifically version 4.2.3), it benefits from an extensive and regularly updated open-source user agent database. The current stable version is 3.0.3, and its release cadence is likely tied to updates from the upstream Matomo project to maintain accuracy and coverage. Key differentiators include its lack of external dependencies, comprehensive TypeScript support, and a rigorous testing suite comprising over 10,000 user agent strings. While it functions in both Node.js and browser environments, the library strongly advises against browser-side usage for performance-critical applications due to its size and processing overhead.

Common errors

```
TypeError: DeviceDetector is not a constructor
```
cause This error typically occurs when attempting to instantiate `DeviceDetector` incorrectly, often by using a named import (`import { DeviceDetector }`) when the module provides a default export, or by mismanaging CommonJS `require()` behavior.

fix For ESM and modern TypeScript, ensure you are using the default import: `import DeviceDetector from 'device-detector-js';`. If using CommonJS in JavaScript, the pattern `const DeviceDetector = require('device-detector-js');` should work, assuming the CommonJS export directly exposes the class. In older TypeScript with CommonJS, follow the documentation's suggestion: `import DeviceDetector = require('device-detector-js');`.
```
Error: Cannot find module 'device-detector-js/dist/parsers/bot'
```
cause Attempting to import sub-modules like `BotDetector` using an incorrect or abbreviated path. These specific parsers are not exposed directly from the main package entry point.

fix Always use the full, explicit path for sub-modules: `import BotDetector from 'device-detector-js/dist/parsers/bot';`.

Warnings

gotcha Running `device-detector-js` directly in a browser environment is strongly discouraged. The library is large and computationally intensive, which can lead to significant performance degradation in client-side applications.
Fix: For performance-critical applications, prefer server-side user agent detection (e.g., in Node.js). If browser-side usage is unavoidable, ensure thorough performance testing and consider alternative, lighter-weight libraries if appropriate.

Install

npm install device-detector-js npm
yarn add device-detector-js yarn
pnpm add device-detector-js pnpm

Imports

DeviceDetector
wrong:
```
import { DeviceDetector } from 'device-detector-js';
```
correct:
```
import DeviceDetector from 'device-detector-js';
```
Use this for ESM and modern TypeScript environments. For CommonJS or older TypeScript configurations, the library documentation suggests `import DeviceDetector = require('device-detector-js');`.
BotDetector
wrong:
```
import { BotDetector } from 'device-detector-js';
```
correct:
```
import BotDetector from 'device-detector-js/dist/parsers/bot';
```
The `BotDetector` class is imported directly from a specific sub-module path, not as a named export from the main `device-detector-js` package.
DeviceDetectorResult, DeviceDetectorOptions
```
import type { DeviceDetectorResult, DeviceDetectorOptions } from 'device-detector-js';
```
These are type definitions provided for TypeScript usage, allowing for strong typing of the parsing results and configuration options.

Quickstart

Demonstrates how to initialize the DeviceDetector and parse a common user agent string, logging the structured client, OS, and device details.

import DeviceDetector from 'device-detector-js';

const deviceDetector = new DeviceDetector();
const userAgent = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.81 Safari/537.36';
const device = deviceDetector.parse(userAgent);

console.log(JSON.stringify(device, null, 2));

view raw JSON →