Registry / web-framework / koa-useragent

koa-useragent

library4.1.0jsnpmunverified

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.

web-framework http-networking

npm install koa-useragent

github ↗package ↗

INSTALL

IMPORT

SIG · KOA-USERAGENT

koa-useragent

web-frameworkjavascriptv4.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 'koa-useragent';

✗ import userAgent from 'koa-useragent';

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.

userAgent (CommonJS)

✓ const { userAgent } = require('koa-useragent');

✗ const userAgent = require('koa-useragent');

CommonJS usage also requires named destructuring for the middleware function, consistent with ESM.

UserAgentContext

✓ import { UserAgentContext } from 'koa-useragent';

Used for augmenting Koa's Context type in TypeScript for explicit `ctx.userAgent` typing.

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.

import Koa, { BaseContext } from 'koa'; import { userAgent, UserAgentContext } from 'koa-useragent'; interface MyContext extends BaseContext, UserAgentContext {} const app = new Koa<Koa.DefaultState, MyContext>(); app.use(userAgent); app.use(async (ctx) => { console.log('User Agent Details:', ctx.userAgent); // Example of using user agent data: if (ctx.userAgent.isMobile) { ctx.body = 'Hello, Mobile User!'; } else if (ctx.userAgent.isBot) { ctx.body = 'Hello, Bot!'; } else { ctx.body = `Hello, ${ctx.userAgent.browser} on ${ctx.userAgent.os}!`; } }); const port = process.env.PORT ?? 3000; app.listen(port, () => { console.log(`Server running on http://localhost:${port}`); console.log('Try accessing with different devices/browsers.'); });

Debug

Known issues

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

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.

affects: >=4.0.0

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

fix

Update imports to use named destructuring: `import { userAgent } from 'koa-useragent';` or `const { userAgent } = require('koa-useragent');`

affects: >=2.1.3 <4.0.0

breakingVersion 3.0.0 introduced breaking changes related to the `geoIp` type. If your application utilized or extended this type, it might require adjustments.

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.

affects: >=3.0.0

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

fix

If Electron detection is critical, you may need to implement custom logic using the raw user-agent string or an alternative library.

affects: >=2.0.0

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

fix

Always use named imports/requires: `import { userAgent } from 'koa-useragent';` or `const { userAgent } = require('koa-useragent');`

affects: >=4.0.0

Errors

Common errors & fixes

Property 'userAgent' does not exist on type 'Context'.

Using `ctx.userAgent` in TypeScript after v4.0.0 without explicitly augmenting Koa's `Context` type.

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

TypeError: userAgent is not a function

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.

fix

Use named imports/destructuring: `import { userAgent } from 'koa-useragent';` for ESM or `const { userAgent } = require('koa-useragent');` for CommonJS.

Error: Cannot find module 'koa-useragent'

The `koa-useragent` package is not installed or not resolvable in the current environment.

fix

Install the package using npm: `npm install koa-useragent` or yarn: `yarn add koa-useragent`.

Upgrade

Version history

4.1.0latest on npm

Audit

Dependencies

useragentrequiredCore library for parsing user-agent strings.

koarequiredPeer dependency, as this is a Koa middleware.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/rvboris/koa-useragent ↗

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