Express User-Agent Parser

Common errors

• TypeError: useragent is not a function

  cause 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

  cause 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)

  cause 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.

Warnings

• breaking Version 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()`.
• gotcha The 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.
• gotcha Prior 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`.
• gotcha In 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())`.

Install

• npm install express-useragent npm
• yarn add express-useragent yarn
• pnpm add express-useragent pnpm

Imports

• UserAgent
  wrong:

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

  correct:

  import { UserAgent } from '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
  wrong:

  import useragentMiddleware from 'express-useragent'

  correct:

  import { express as 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
  wrong:

  import useragent from 'express-useragent'

  correct:

  const useragent = require('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.

Quickstart

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}`);
});