{"id":17095,"library":"express-useragent","title":"Express User-Agent Parser","description":"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.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"git://github.com/biggora/express-useragent","tags":["javascript","useragent","connect","express","trinte","browser","compound","middleware","typescript"],"install":[{"cmd":"npm install express-useragent","lang":"bash","label":"npm"},{"cmd":"yarn add express-useragent","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-useragent","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for using the Express.js middleware; implicitly assumed as a peer dependency for Express applications.","package":"express","optional":false}],"imports":[{"note":"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`.","wrong":"const { UserAgent } = require('express-useragent')","symbol":"UserAgent","correct":"import { UserAgent } from 'express-useragent'"},{"note":"Since v2.0.0, the Express middleware is a named export (`express`, aliased `useragentMiddleware` for clarity). The default export is the `UserAgent` class.","wrong":"import useragentMiddleware from 'express-useragent'","symbol":"express","correct":"import { express as useragentMiddleware } from 'express-useragent'"},{"note":"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.","wrong":"import useragent from 'express-useragent'","symbol":"useragent","correct":"const useragent = require('express-useragent')"}],"quickstart":{"code":"import express from 'express';\nimport { express as useragent } from 'express-useragent';\n\nconst app = express();\n\n// Apply the user-agent middleware\napp.use(useragent());\n\n// Define a route to display parsed user-agent data\napp.get('/', (req, res) => {\n  if (!req.useragent) {\n    return res.status(500).json({ error: 'User-agent data not found' });\n  }\n  res.json({\n    browser: req.useragent.browser,\n    os: req.useragent.os,\n    isMobile: req.useragent.isMobile,\n    platform: req.useragent.platform,\n    source: req.useragent.source\n  });\n});\n\nconst PORT = process.env.PORT ?? 3000;\napp.listen(PORT, () => {\n  console.log(`Server listening on port ${PORT}`);\n});","lang":"typescript","description":"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."},"warnings":[{"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()`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your Node.js runtime environment is at least version 18.0.0.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade to version 2.1.0 or newer to ensure correct and consistent boolean output for `isBot`.","message":"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).","severity":"gotcha","affected_versions":"<2.1.0"},{"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())`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Correct the import statement for the middleware: `import { express as useragentMiddleware } from 'express-useragent'; app.use(useragentMiddleware());`","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())`.","error":"TypeError: useragent is not a function"},{"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.","cause":"You are attempting to use CommonJS `require()` syntax in an ES Module context, or vice-versa, without proper configuration or loaders.","error":"ERR_REQUIRE_ESM or ReferenceError: require is not defined"},{"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.","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.","error":"Property 'useragent' does not exist on type 'Request'. (TypeScript)"}],"ecosystem":"npm","meta_description":null}