node-device-detector

Last update: 27/08/2025

Description

Port php lib matomo-org/device-detector to NodeJs

• Online demo

Code Status

Contents

• Helpers
• Single parsers
• Settings
• Specific methods
• Examples
• Support brands
• Support device types
• Support browsers

Install -

npm install node-device-detector --save

or

yarn add node-device-detector

Usage -

// commonJS
const DeviceDetector = require('node-device-detector');
// or ESModule
import DeviceDetector from "node-device-detector";

const detector = new DeviceDetector({
  clientIndexes: true,
  deviceIndexes: true,
  osIndexes: true,
  deviceAliasCode: false,
  deviceTrusted: false,
  deviceInfo: false,
  maxUserAgentSize: 500,
});
const userAgent = 'Mozilla/5.0 (Linux; Android 5.0; NX505J Build/KVT49L) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.78 Mobile Safari/537.36';
const result = detector.detect(userAgent);
console.log('result parse', result);

Result parse

{ 
  os: { 
    name: 'Android',           // os name       
    short_name: 'AND',         // os short code name (format A-Z0-9{3})
    version: '5.0',            // os version
    platform: '',              // os platform (x64, x32, amd etc.)
    family: 'Android'          // os family
  },
  client:  { 
    type: 'browser',            // client type 
    name: 'Chrome Mobile',      // client name name
    short_name: 'CM',           // client short code name (only browser, format A-Z0-9{2,3})
    version: '43.0.2357.78',    // client version
    engine: 'Blink',            // client engine name (only browser)
    engine_version: ''          // client engine version (only browser)
    family: 'Chrome'            // client family (only browser)
  },
  device: { 
    id: 'ZT',                   // short code device brand name (format A-Z0-9{2,3})
    type: 'smartphone',         // device type
    brand: 'ZTE',               // device brand name
    model: 'Nubia Z7 max'       // device model name
    code: 'NX505J'              // device model code  (only result for enable detector.deviceAliasCode) 
    trusted: true               // device trusted (result only for enable detector.deviceTrusted and have fixture data + ClientHints are required)
    info: {}                    // device specs (result only fir enable detector.deviceInfo)
  }
}

Result parse empty

{ 
  os: {},                      // empty objects its os not found
  client: {},                  // empty objects its client not found
  device: {      
    id: '',                    // empty string its device brand not found
    type : 'device type',      // device type or empty string
    brand: '',                 // empty string its device brand not found
    model: ''                  // empty string its device model not found
  }
}

Helpers

[top]

// commonJS
const DeviceDetector = require('node-device-detector');
const DeviceHelper = require('node-device-detector/helper');
// or ESModule
import DeviceDetector from "node-device-detector";
import DeviceHelper from "node-device-detector/helper";

const detector = new DeviceDetector();
const userAgent = 'Mozilla/5.0 (Linux; Android 5.0; NX505J Build/KVT49L) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.78 Mobile Safari/537.36';
const result = detector.detect(userAgent);

/* check device type (feature phone, smartphone or phablet) */
DeviceHelper.isMobile(result);
/* check device type is desktop */
DeviceHelper.isDesktop(result);
/* check device type is tablet  */
DeviceHelper.isTablet(result);
/* check device type car (side panel in car)  */
DeviceHelper.isCar(result);
/* check device type feature phone (push-button telephones)  */
DeviceHelper.isFeaturePhone(result);
/* check device type smartphone  */
DeviceHelper.isSmartphone(result);
/* check device type phablet  */
DeviceHelper.isPhablet(result);
/* check device type game console (xBox, PlayStation, Nintendo etc)  */
DeviceHelper.isConsole(result);
/* check device type smart speaker (Alisa, Alexa, HomePod etc) */
DeviceHelper.isSmartSpeaker(result);
/* check device type SmartTV/TV box */
DeviceHelper.isTv(result);
/* check device type portable camera */
DeviceHelper.isCamera(result);
/* portable terminal, portable projector */
DeviceHelper.isPeripheral(result);
/* LCD panel or interactive panel  */
DeviceHelper.isSmartDisplay(result);
/* check device type boxes, blu-ray players */
DeviceHelper.isPortableMediaPlayer(result);
/* check device type watches, headsets */
DeviceHelper.isWearable(result);
/* result device type number id */
DeviceHelper.getDeviceTypeId(result);
/* result device type string */
DeviceHelper.getDeviceType(result);
/* result client type string */
DeviceHelper.getClientType(result);

Using DeviceDetector + ClientHints - [top]

// commonJS
const DeviceDetector = require('node-device-detector');
const DeviceHelper   = require('node-device-detector/helper');
const ClientHints    = require('node-device-detector/client-hints');
// or ESModule
import DeviceDetector from "node-device-detector";
import DeviceHelper from "node-device-detector/helper";
import ClientHints from "node-device-detector/client-hints";

const detector = new DeviceDetector({
  clientIndexes: true,
  deviceIndexes: true,
  osIndexes: true,
  deviceAliasCode: false,
  deviceTrusted: false,
  deviceInfo: false,
  // ... all options scroll to Setter/Getter/Options
});

/** server side use celint hinsts */
const clientHints = new ClientHints();
const userAgent = res.headers['user-agent'];
let headers = res.headers;
let meta = {}
/**
 option meta interface (needed to detect whether the device is trusted,
 this information can be obtained from browser)
 {
   width: '720',             //  Math.ceil(window.screen.width)
   height: '1440',           //  Math.ceil(window.screen.height)
   gpu: 'PowerVR SGX Doma',  //  (()=>{let e=document.createElement("canvas"),t=e.getContext("webgl")||e.getContext("experimental-webgl");return t?t.getParameter(t.getExtension("WEBGL_debug_renderer_info").UNMASKED_RENDERER_WEBGL):null})();
 }
 More details in file docs/CLIENT_HINTS_BROWSER.MD
 */
let hints = clientHints.parse(headers /* or body.hints */, meta /* or body.meta */);
const result = detector.detect(userAgent, hints);

// result promise
// added for 2.0.4 version or later
const result = detector.detectAsync(userAgent, hints);

Using parsers singly - [top]

Detect Bot

// commonJS
const DeviceDetector = require('node-device-detector');
// or ESModule
import DeviceDetector from "node-device-detector";

const userAgent = 'Mozilla/5.0 (iPhone; CPU iPhone OS 6_0 like Mac OS X) AppleWebKit/536.26 (KHTML, like Gecko) Version/6.0 Mobile/10A5376e Safari/8536.25 (compatible; Googlebot-Mobile/2.1; +http://www.google.com/bot.html)';
const detector = new DeviceDetector();
const result = detector.parseBot(userAgent);

Detect Os

// commonJS
const DeviceDetector = require('node-device-detector');
// or ESModule
import DeviceDetector from "node-device-detector";

const userAgent = 'Mozilla/5.0 (Linux; Android 5.0; NX505J Build/KVT49L) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.78 Mobile Safari/537.36';
const detector = new DeviceDetector({
  clientIndexes: true,
  osIndexes: true,
  deviceIndexes: true,
  deviceAliasCode: false,
});
const result = detector.parseOs(userAgent/*, clientHintData*/);
console.log('Result parse os', result);

Detect Client

// commonJS
const DeviceDetector = require('node-device-detector');
// or ESModule
import DeviceDetector from "node-device-detector";

const userAgent = 'Mozilla/5.0 (Linux; Android 5.0; NX505J Build/KVT49L) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.78 Mobile Safari/537.36';
const detector = new DeviceDetector({
    clientIndexes: true,
    deviceIndexes: true,
    osIndexes: true,
    deviceAliasCode: false,
});
const result = detector.parseClient(userAgent/*, clientHintData*/);
console.log('Result parse client', result);

Lite parse not detect brand

// commonJS
const DeviceDetector = require('node-device-detector');
// or ESModule
import DeviceDetector from "node-device-detector";

const userAgent = 'Mozilla/5.0 (Linux; Android 5.0; NX505J Build/KVT49L) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.78 Mobile Safari/537.36';
const detector = new DeviceDetector({
  clientIndexes: true,
  deviceIndexes: true,
  osIndexes: true,
  deviceAliasCode: false,
});
const resultOs = detector.parseOs(userAgent);
const resultClient = detector.parseClient(userAgent);
const resultDeviceType = detector.parseDeviceType(
 userAgent,
 resultOs,
 resultClient,
 {},
 /*, clientHintData */
);
const result = Object.assign({os:resultOs}, {client:resultClient}, {device: resultDeviceType});
console.log('Result parse lite', result);

Getter/Setter/Options

[top]

const detector = new DeviceDetector({
  osVersionTruncate: 0,      // Truncate OS version from 5.0 to 5 (default '' or null)
  clientVersionTruncate: 2,  // Truncate Client version Chrome from 43.0.2357.78 to 43.0.2357 (default '' or null)
  deviceIndexes: true,       // Using indexes for faster device search (default false)
  clientIndexes: true,       // Using indexes for faster client search (default false)
  osIndexes: true,           // Using indexes for faster os search (default false)
  deviceAliasCode: true,     // adds device code to result [device.code] as is (default false)
  maxUserAgentSize: 500,     // uses only 500 chars from useragent string (default null - unlimited)
  deviceTrusted: true,       // check device by specification (default false)
  deviceInfo: true,          // adds device specification to result [device.info] (default false)
});

// You can override these settings at any time using special setters, example
detector.osVersionTruncate = 0;
detector.clientVersionTruncate = 2;
detector.deviceIndexes = true;
detector.clientIndexes = true;
detector.osIndexes = true;
detector.deviceAliasCode = true;
detector.maxUserAgentSize = 500;
detector.deviceTrusted = true;
detector.deviceInfo = true;

// Array available device types
detector.getAvailableDeviceTypes();
// Array available devices brands
detector.getAvailableBrands();
// Array available browsers
detector.getAvailableBrowsers();

Specific methods

const DEVICE_PARSER_NAMES = detector.getDeviceParserNames(); // result colection names for device parsers 
const CLIENT_PARSER_NAMES = detector.getClientParserNames(); // result colection names for client parsers 
const OS_PARSER_NAMES = detector.getOsParserNames();         // result collection names for os parsers
const BOT_PARSER_NAMES = detector.getBotParserNames();       // result collection names for bot parsers   

const aliasDevice = detector.getParseAliasDevice();          // result AliasDevice parser
const deviceInfo = detector.getParseInfoDevice();            // result InfoDevice parser

// added custom parser
detector.addParseDevice('MyDeviceParser', new MyDeviceParser());
detector.addParseClient('MyClientParser', new MyClientParser());
detector.addParseOs('MyOsParser', new MyOsParser());
detector.addParseBot('MyBotParser', new MyBotParser());
// get single parser by name
detector.getParseDevice('MyDeviceParser' /* or DEVICE_PARSER_NAMES.MOBILE */);
detector.getParseClient('MyClientParser'  /* or CLIENT_PARSER_NAMES.BROWSER */);
detector.getParseOs('MyOsParser'/* or OS_PARSER_NAMES.DEFAULT */);
detector.getParseBot('MyBotParser');

Getting device code as it (experimental)

[top]

const DeviceDetector = require('node-device-detector');
const detector = new DeviceDetector()
const aliasDevice = detector.getParseAliasDevice();
const result = aliasDevice.parse(userAgent);
console.log('Result parse code model', result);
// or
const AliasDevice = require('node-device-detector/parser/device/alias-device');
const userAgent = 'Mozilla/5.0 (Linux; Android 5.0; NX505J Build/KVT49L) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.78 Mobile Safari/537.36';
const aliasDevice = new AliasDevice();
const result = aliasDevice.parse(userAgent);
console.log('Result parse code model', result);

/*
result 
{
  name: "NX505J"
}
is not parse result  {name: ""}
*/

What about performance?

node tests/banchmark.js test result:

UA Mozilla/5.0 (Linux; Android 5.0; NX505J Build/KVT49L) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.78 Mobile Safari/537.36
-----
┌──────────────────────┬─────────┬──────────┬─────────────────┬──────────────┐
│    parse method      │ indexes │ ops/sec  │ margin of error │ runs sampled │
├──────────────────────┼─────────┼──────────┼─────────────────┼──────────────┤
│ detector.parseDevice │  'on'   │ '20,235' │    '±0.26%'     │      98      │
│ detector.parseClient │  'on'   │ '46,058' │    '±0.34%'     │      98      │
│   detector.parseOS   │  'on'   │ '20,317' │    '±0.32%'     │      97      │
│   detector.detect    │  'on'   │ '7,526'  │    '±0.76%'     │      92      │
└──────────────────────┴─────────┴──────────┴─────────────────┴──────────────┘

What about tests?

Yes we use tests, total tests: ~84.2k

Get more information about a device (experimental)

This parser is experimental and contains few devices. (2156 devices, alias devices 3998)

Support detail brands/models list:

const DeviceDetector = require('node-device-detector');
const detector = new DeviceDetector();
const infoDevice = detector.getParseInfoDevice();
const result = infoDevice.info('Asus', 'Zenfone 4');
console.log('Result information', result);
// or 
const InfoDevice = require('node-device-detector/parser/device/info-device');
const infoDevice = new InfoDevice();
const result = infoDevice.info('Asus', 'Zenfone 4');
console.log('Result information', result);

/*
result
{
  display: {
    size: '5.5',
    resolution: '1080x1920',  // width+height
    ratio: '16:9',
    ppi: "401"
  },
  size: '155.4x75.2x7.7',    // width+height+thickness
  weight: '165',
  hardware: {
    // ...
  }
  os: "Android 7.1",
  release: "2017.08",
  sim": "2",
}
is not found result null
*/

Cast methods

const InfoDevice = require('node-device-detector/parser/device/info-device');
const infoDevice = new InfoDevice;
infoDevice.setSizeConvertObject(true);
infoDevice.setResolutionConvertObject(true);
const result = infoDevice.info('Asus', 'Zenfone 4');
console.log('Result information', result);
/*
result
{  
  display: {
    size: "5.5",  // value in inchs
    resolution: {
      width: "1080", // value in px
      height: "1920" // value in px
    },
    ratio: "16:9",   // calculated field
    ppi: "401"       // calculated field
  },
  hardware: {
    ram: "4096",   // RAM value in megabytes
    cpu_id: 19,  // id cpu model in collection
    cpu: {
      name: "Qualcomm Snapdragon 630",  // brand + name
      type: "ARM",                      // architecture type 
      cores: "8",                       // number of cores / threads 
      clock_rate: 2200,                 // value in MHz
      gpu_id: 16                        // id gpu model in collection
    },
    gpu: {
      name: "Qualcomm Adreno 508",
      clock_rate: 650
    }
  },
  os: "Android 7.1",   // initial OS version
  release: "2017.08",  // date release or anonce
  sim": "2",           // count SIM 
  size: {           
    width: "75.2",     // physical width in millimeters
    height: "155.4",   // physical height in millimeters
    thickness: "7.7"   // physical thickness in millimeters
  },
  weight: "165"        // in grams
};
*/

Others - [top]

Examples

• detect device in native server
• detect device + client hints in native server
• detect device in express.js
• detect device in moleculer.js
• detect device in uws.js
• detect device in typescript
• get client hints in browser

Support detect brands list (2096):

[top]

Support detect browsers list (681):

[top]