# express-useragent

> JS Library & ExpressJS user-agent middleware exposing

Latest version **2.2.3** (published 2026-08-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install express-useragent
pnpm add express-useragent
yarn add express-useragent
bun add express-useragent
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.2.3 |
| Published | 2026-08-22 |
| First published | 2012-03-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 409.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 651 |
| Author | Aleksejs Gordejevs |
| Maintainers | biggora |
| Keywords | useragent, connect, express, trinte, browser, compound, middleware |

## Links

- npm: https://www.npmjs.com/package/express-useragent
- Repository: https://github.com/biggora/express-useragent
- Homepage: https://github.com/biggora/express-useragent/
- Issues: https://github.com/biggora/express-useragent/issues
- npm.io page: https://npm.io/package/express-useragent

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 2.2.3 (latest) — 2026-08-22
- 2.1.1-oidc-test.0 (oidc-test) — 2026-05-09
- 2.2.2 — 2026-08-14
- 2.2.1 — 2026-06-30
- 2.2.0 — 2026-05-16
- 2.1.1 — 2026-05-10
- 2.1.0 — 2026-01-25
- 2.0.2 — 2025-11-09
- 2.0.1 — 2025-10-30
- 2.0.0 — 2025-10-30
- 1.0.15 — 2020-07-11
- 1.0.14 — 2020-07-10
- 1.0.13 — 2019-07-16
- 1.0.12 — 2018-02-07
- 1.0.11 — 2018-02-07
- … 40 more at https://npm.io/package/express-useragent/versions

## README

[![npm version](https://img.shields.io/npm/v/express-useragent.svg)](https://www.npmjs.com/package/express-useragent)
[![CI](https://img.shields.io/github/actions/workflow/status/biggora/express-useragent/ci.yml?branch=master)](https://github.com/biggora/express-useragent/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

# express-useragent

Fast user-agent parser with first-class Express middleware and TypeScript typings. Works server-side in Node.js and in the browser via a lightweight IIFE bundle.

[Express UserAgent Demo](https://biggora.github.io/express-useragent/)

> Requires Node.js 18 or newer.

## Install

```bash
npm install express-useragent
```

## Quick Start

```ts
import http from 'node:http';
import { UserAgent } from 'express-useragent';

const server = http.createServer((req, res) => {
  const source = req.headers['user-agent'] ?? 'unknown';
  const parser = new UserAgent().hydrate(source);

  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify(parser.Agent));
});

server.listen(3000);
```

### Express Middleware

ESM usage (Node 18+):

```ts
import express from 'express';
import { express as useragent } from 'express-useragent';

const app = express();

app.use(useragent());

app.get('/', (req, res) => {
  res.json({
    browser: req.useragent?.browser,
    os: req.useragent?.os,
  });
});

app.listen(3000);
```

Alternatively, you can import the whole namespace:

```ts
import express from 'express';
import * as useragent from 'express-useragent';

const app = express();

app.use(useragent.express());

app.get('/', (req, res) => {
  res.json({
    browser: req.useragent?.browser,
    os: req.useragent?.os,
  });
});

app.listen(3000);
```

CommonJS (require) still supports the default export pattern used in older examples:

```js
const express = require('express');
const useragent = require('express-useragent');

const app = express();

app.use(useragent.express());

app.get('/', (req, res) => {
  res.json({
    browser: req.useragent?.browser,
    os: req.useragent?.os,
  });
});

app.listen(3000);
```

### ESM vs CJS at a glance

- ESM (Node 18+):
  - Named import of middleware:
    ```ts
    import { express as useragent } from 'express-useragent';
    app.use(useragent());
    ```
  - Namespace import:
    ```ts
    import * as useragent from 'express-useragent';
    app.use(useragent.express());
    ```
- CommonJS (require):
  ```js
  const useragent = require('express-useragent');
  app.use(useragent.express());
  ```

### Migrating from v1.x to v2.x

- In v1.x, `import useragent from 'express-useragent'` returned an object with an `.express()` method used as middleware.
- In v2.x, the default export is a parser instance (for direct parsing). The Express middleware is provided as a named export `express` (and alias `useragentMiddleware`). Use one of:
  - `import { express as useragent } from 'express-useragent'` → `app.use(useragent())`
  - `import * as useragent from 'express-useragent'` → `app.use(useragent.express())`
- CommonJS `require('express-useragent').express()` continues to work unchanged.

See more end-to-end demos under `examples/`:
- `examples/server.ts` — Express middleware demo
- `examples/http.ts` — raw Node HTTP sample

## API Highlights

- `new UserAgent()` — build a fresh parser instance.
- `useragent.parse(source)` — quick parse returning the agent snapshot.
- `useragent.express()` — Express-compatible middleware that hydrates `req.useragent` and `res.locals.useragent`.
- `parser.Agent` — normalized fingerprint with convenience booleans (`isMobile`, `isBot`, etc.).

Sample payload:

```json
{
  "isMobile": false,
  "isDesktop": true,
  "isBot": false,
  "browser": "Chrome",
  "version": "118.0.0",
  "os": "macOS Sonoma",
  "platform": "Apple Mac",
  "source": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0)..."
}
```

## Browser Usage

The build exports drop-in browser bundles under `dist/browser/`:

- `express-useragent.global.js` — readable IIFE that exposes `window.UserAgent` and `window.useragent`.
- `express-useragent.global.min.js` — minified version of the same API.

```html
<script src="/vendor/express-useragent.global.min.js"></script>
<script>
  const agent = new UserAgent().parse(navigator.userAgent);
  console.log(agent.browser, agent.version);
</script>
```

Prefer consuming the ESM/CJS entry from your bundler when possible:

```ts
import { UserAgent } from 'express-useragent';

const agent = new UserAgent().parse(navigator.userAgent);
```

## Scripts

```bash
npm install        # install dependencies
npm run lint       # lint the TypeScript sources, tests, and examples
npm run typecheck  # run the TypeScript compiler in noEmit mode
npm test           # execute Vitest (includes adapted legacy suites)
npm run build      # emit dist/ (CJS, ESM, d.ts, browser bundles)
```

Examples for manual testing:

```bash
npm run http      # raw Node HTTP sample
npm run express   # Express middleware demo
npm run simple    # CLI parsing helper
```

## Contributing

Bug reports and PRs are welcome. When submitting changes, please include:

- Updated tests under `tests/` covering new parsing behaviour.
- `npm test` and `npm run lint` output or reproduction steps.
- Notes in the changelog for breaking updates.

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines, including how to update the bot list.

## License

[MIT](LICENSE) © Aleksejs Gordejevs and contributors.

---
_Source: https://npm.io/package/express-useragent · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._