{"id":17761,"library":"koa-useragent","title":"Koa User-Agent Detection Middleware","description":"koa-useragent is a Koa.js middleware designed for detecting and parsing user-agent strings from incoming HTTP requests. It enriches the Koa context (`ctx`) with a `userAgent` object containing detailed information such as browser, OS, device type (mobile, desktop, bot), and version. The package is currently at version `4.1.0`, released in July 2022, and appears to maintain an active development status, although major version releases have slowed since 2020. Key differentiators include its tight integration with Koa's context, providing structured user-agent data directly for use in middleware and route handlers, and its robust TypeScript support, which has been a focus since version 2.1.0 and refined in subsequent major releases. It is built upon the well-established `useragent` library for reliable parsing.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/rvboris/koa-useragent","tags":["javascript","koa","middleware","useragent","typescript"],"install":[{"cmd":"npm install koa-useragent","lang":"bash","label":"npm"},{"cmd":"yarn add koa-useragent","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-useragent","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core library for parsing user-agent strings.","package":"useragent","optional":false},{"reason":"Peer dependency, as this is a Koa middleware.","package":"koa","optional":false}],"imports":[{"note":"The main middleware function is a named export since v2.1.3. While v4.0.0 changelog mentions 'add default export', the primary middleware remains a named export in current usage.","wrong":"import userAgent from 'koa-useragent';","symbol":"userAgent","correct":"import { userAgent } from 'koa-useragent';"},{"note":"CommonJS usage also requires named destructuring for the middleware function, consistent with ESM.","wrong":"const userAgent = require('koa-useragent');","symbol":"userAgent (CommonJS)","correct":"const { userAgent } = require('koa-useragent');"},{"note":"Used for augmenting Koa's Context type in TypeScript for explicit `ctx.userAgent` typing.","symbol":"UserAgentContext","correct":"import { UserAgentContext } from 'koa-useragent';"}],"quickstart":{"code":"import Koa, { BaseContext } from 'koa';\nimport { userAgent, UserAgentContext } from 'koa-useragent';\n\ninterface MyContext extends BaseContext, UserAgentContext {}\n\nconst app = new Koa<Koa.DefaultState, MyContext>();\n\napp.use(userAgent);\n\napp.use(async (ctx) => {\n  console.log('User Agent Details:', ctx.userAgent);\n  // Example of using user agent data:\n  if (ctx.userAgent.isMobile) {\n    ctx.body = 'Hello, Mobile User!';\n  } else if (ctx.userAgent.isBot) {\n    ctx.body = 'Hello, Bot!';\n  } else {\n    ctx.body = `Hello, ${ctx.userAgent.browser} on ${ctx.userAgent.os}!`;\n  }\n});\n\nconst port = process.env.PORT ?? 3000;\napp.listen(port, () => {\n  console.log(`Server running on http://localhost:${port}`);\n  console.log('Try accessing with different devices/browsers.');\n});","lang":"typescript","description":"Demonstrates setting up `koa-useragent` middleware, augmenting Koa's context type for TypeScript, and accessing parsed user-agent details in a downstream middleware to respond based on client type."},"warnings":[{"fix":"For TypeScript, define an interface extending `Koa.BaseContext` and `UserAgentContext`, then use it in your Koa app instantiation, e.g., `const app = new Koa<Koa.DefaultState, MyContext>();` where `MyContext` extends both.","message":"Starting with v4.0.0, the automatic modification of Koa's `Context` type for `ctx.userAgent` was removed. TypeScript users must explicitly augment the `Koa.Context` or use an interface extension to correctly type `ctx.userAgent` and avoid compilation errors.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update imports to use named destructuring: `import { userAgent } from 'koa-useragent';` or `const { userAgent } = require('koa-useragent');`","message":"In v2.1.3, the primary middleware `userAgent` changed from a default export to a named export. Code relying on `import userAgent from 'koa-useragent';` or `const userAgent = require('koa-useragent');` will break.","severity":"breaking","affected_versions":">=2.1.3 <4.0.0"},{"fix":"Review the `geoIp` related types and their usage in your codebase, adapting to the new structure or definitions provided in `koa-useragent` v3 and later.","message":"Version 3.0.0 introduced breaking changes related to the `geoIp` type. If your application utilized or extended this type, it might require adjustments.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"If Electron detection is critical, you may need to implement custom logic using the raw user-agent string or an alternative library.","message":"Version 2.0.0 removed the 'electron check' functionality. Applications that relied on specific detection for Electron environments will no longer have this out-of-the-box support.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always use named imports/requires: `import { userAgent } from 'koa-useragent';` or `const { userAgent } = require('koa-useragent');`","message":"Despite a v4.0.0 changelog entry mentioning 'add default export', the recommended and documented usage for the main `userAgent` middleware remains a named export (`{ userAgent }`) for both CommonJS and ESM. Relying on a default export might lead to unexpected behavior or future breaking changes.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Extend `Koa.BaseContext` with `UserAgentContext` in a custom interface and apply it to your Koa app, e.g., `interface MyContext extends BaseContext, UserAgentContext {} const app = new Koa<Koa.DefaultState, MyContext>();`","cause":"Using `ctx.userAgent` in TypeScript after v4.0.0 without explicitly augmenting Koa's `Context` type.","error":"Property 'userAgent' does not exist on type 'Context'."},{"fix":"Use named imports/destructuring: `import { userAgent } from 'koa-useragent';` for ESM or `const { userAgent } = require('koa-useragent');` for CommonJS.","cause":"Incorrectly importing `userAgent` as a default export (`import userAgent from 'koa-useragent';` or `const userAgent = require('koa-useragent');`) when it is a named export. This was a breaking change in v2.1.3 and applies to current versions.","error":"TypeError: userAgent is not a function"},{"fix":"Install the package using npm: `npm install koa-useragent` or yarn: `yarn add koa-useragent`.","cause":"The `koa-useragent` package is not installed or not resolvable in the current environment.","error":"Error: Cannot find module 'koa-useragent'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}