Registry / http-networking / express-useragent

express-useragent

library2.1.0jsnpmunverified

express-useragent is a robust and fast user-agent parsing library designed for Node.js environments, offering dedicated Express.js middleware and comprehensive TypeScript typings. Currently stable at version 2.1.0, the package underwent a significant rewrite in version 2.0.0, migrating to ES Modules and TypeScript, and now requires Node.js 18 or newer. Its release cadence appears active, with recent patches addressing bug fixes and dependency updates. Key differentiators include its first-class integration with Express, which populates `req.useragent` with parsed data, and its ability to parse user-agent strings directly via a `UserAgent` class instance. It also provides lightweight browser bundles for client-side parsing.

http-networking web-framework

npm install express-useragent

github ↗package ↗

INSTALL

IMPORT

SIG · EXPRESS-USERAGENT

express-useragent

http-networkingjavascriptv2.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

UserAgent

✓ import { UserAgent } from 'express-useragent'

✗ const { UserAgent } = require('express-useragent')

The `UserAgent` class is the default export in ESM contexts if not imported via named import, but explicit named import is clearer. CommonJS users would access it via `require('express-useragent').UserAgent`.

express

✓ import { express as useragentMiddleware } from 'express-useragent'

✗ import useragentMiddleware from 'express-useragent'

Since v2.0.0, the Express middleware is a named export (`express`, aliased `useragentMiddleware` for clarity). The default export is the `UserAgent` class.

useragent

✓ const useragent = require('express-useragent')

✗ import useragent from 'express-useragent'

In CommonJS, `require('express-useragent')` returns an object where the middleware is accessible via `useragent.express()`. In ESM, the default import is the `UserAgent` class, not the middleware.

This quickstart demonstrates how to integrate `express-useragent` middleware into an Express.js application to parse the user-agent string and expose the parsed data on `req.useragent` for easy access within route handlers.

import express from 'express'; import { express as useragent } from 'express-useragent'; const app = express(); // Apply the user-agent middleware app.use(useragent()); // Define a route to display parsed user-agent data app.get('/', (req, res) => { if (!req.useragent) { return res.status(500).json({ error: 'User-agent data not found' }); } res.json({ browser: req.useragent.browser, os: req.useragent.os, isMobile: req.useragent.isMobile, platform: req.useragent.platform, source: req.useragent.source }); }); const PORT = process.env.PORT ?? 3000; app.listen(PORT, () => { console.log(`Server listening on port ${PORT}`); });

Debug

Known issues

breakingVersion 2.0.0 introduced significant breaking changes, including a migration to ES Modules and TypeScript. The default export changed from the Express middleware factory to the `UserAgent` class instance.

fix

For ESM, use `import { express as useragentMiddleware } from 'express-useragent'` for the middleware. CommonJS `require()` patterns remain largely compatible for the middleware via `require('express-useragent').express()`.

affects: >=2.0.0

gotchaThe package now requires Node.js 18 or newer due to its ES Module and TypeScript rewrite in v2.0.0. Older Node.js versions will likely encounter syntax or runtime errors.

fix

Ensure your Node.js runtime environment is at least version 18.0.0.

affects: >=2.0.0

gotchaPrior to v2.1.0, the `isBot` property could exhibit inconsistent behavior, sometimes returning non-boolean values or producing false positives for certain user agents (e.g., TikTok).

fix

Upgrade to version 2.1.0 or newer to ensure correct and consistent boolean output for `isBot`.

affects: <2.1.0

gotchaIn ESM, attempting to use `import useragent from 'express-useragent'` and then `app.use(useragent())` will fail, as the default export is the `UserAgent` class (for direct parsing), not the middleware factory.

fix

Use a named import for the middleware: `import { express as useragentMiddleware } from 'express-useragent'`, or use a namespace import: `import * as useragent from 'express-useragent'` and then `app.use(useragent.express())`.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: useragent is not a function

In an ES Module project (`"type": "module"` in `package.json`), you are likely trying to import the default export as the middleware (`import useragent from 'express-useragent'`) and then calling `app.use(useragent())`.

fix

Correct the import statement for the middleware: `import { express as useragentMiddleware } from 'express-useragent'; app.use(useragentMiddleware());`

ERR_REQUIRE_ESM or ReferenceError: require is not defined

You are attempting to use CommonJS `require()` syntax in an ES Module context, or vice-versa, without proper configuration or loaders.

fix

Ensure your module system (ESM or CommonJS) matches your import/require statements. If in ESM, use `import` statements; if in CommonJS, use `require()` and ensure your project isn't configured as an ESM-only package.

Property 'useragent' does not exist on type 'Request'. (TypeScript)

Your TypeScript environment is not correctly recognizing the augmentation of the `express.Request` interface by the middleware, or the types are not being picked up.

fix

Ensure you have `import 'express-useragent';` (or similar, depending on your project structure) in a global declaration file or an entry point. The package ships its types, so this usually indicates a setup issue.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

expressrequiredRequired for using the Express.js middleware; implicitly assumed as a peer dependency for Express applications.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/biggora/express-useragent ↗

packagehttps://www.npmjs.com/package/express-useragent ↗