# @financial-times/user-agent

> A library to generate user-agent strings that conform to the FT standard

Latest version **3.0.0** (published 2026-08-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install @financial-times/user-agent
pnpm add @financial-times/user-agent
yarn add @financial-times/user-agent
bun add @financial-times/user-agent
```

## Health

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

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2026-08-03 |
| First published | 2024-06-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | 22.x \|\| 24.x \|\| 26.x |
| Dependencies | 1 |
| Unpacked size | 11.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | the-ft, rowanmanning, chee, alexwilson, aendra, emmalewis, notlee, hamza.samih, robertboulton, leila.micollier, robgodfrey |

## Links

- npm: https://www.npmjs.com/package/@financial-times/user-agent
- Repository: https://github.com/Financial-Times/user-agent-node
- Issues: https://github.com/Financial-Times/user-agent-node/issues
- npm.io page: https://npm.io/package/@financial-times/user-agent

## Dependencies (1)

- [@dotcom-reliability-kit/app-info](https://npm.io/package/@dotcom-reliability-kit/app-info.md) ^5.0.1

## Recent versions

- 3.0.0 (latest) — 2026-08-03
- 2.2.0 — 2026-03-10
- 2.1.0 — 2025-05-09
- 2.0.1 — 2025-03-26
- 2.0.0 — 2025-01-23
- 1.0.5 — 2024-12-03
- 1.0.4 — 2024-07-03
- 1.0.3 — 2024-06-27
- 1.0.2 — 2024-06-26
- 1.0.1 — 2024-06-25
- 1.0.0 — 2024-06-25

## README

# @financial-times/user-agent

A library to generate user-agent strings that conform to the [FT standard](https://docs.google.com/document/d/1fSrPlPKwJyL69iLi8MXygFe-TzfiKAEler21smAJicM/edit).

* [Usage](#usage)
  * [`buildUserAgent`](#builduseragent)
    * [`libraries` option](#libraries-option)
    * [`urls` option](#urls-option)
* [License](#license)


## Usage

Install `@financial-times/user-agent` as a dependency:

```bash
npm install --save @financial-times/user-agent
```

Include in your code:

```js
import { buildUserAgent } from '@financial-times/user-agent';
// or
const { buildUserAgent } = require('@financial-times/user-agent');
```

### `buildUserAgent`

The `buildUserAgent` function can be used to generate a user-agent string based on the app that the function is run in. It uses the [Reliability Kit app-info package](https://github.com/Financial-Times/dotcom-reliability-kit/tree/main/packages/app-info#readme) to determine a system code and version as follows:

  * **System code:** use the `SYSTEM_CODE` environment variable. Otherwise, fall back to `name` in `CWD/package.json`. If neither is present, use `unknown`.

  * **Version:** use the `HEROKU_RELEASE_VERSION` environment variable, then the `AWS_LAMBDA_FUNCTION_VERSION` environment variable, Otherwise, fall back to `version` in `CWD/package.json`. If none are present, use `0.0.0`.

It also includes the Node.js version. E.g.

```js
buildUserAgent();
// "FTSystem/myapp/1.2.3 (Node.js/22.13.1)"
```

You can optionally pass in options to `buildUserAgent` to change the output. These options can all be used together.

#### `hash` option

If you pass in an options object with a `hash` property (`string`), then this hash will be added to the generated user-agent, allowing us to verify it when it makes requests to FT properties. This hash **MUST NOT** be a secret but it must be predictable (e.g. not generated per-request). We recommend generating a hash with:

```sh
echo -n "a key phrase you decide on, it doesn't matter, it should just be unique" | openssl dgst -sha256
```

```js
buildUserAgent({ hash: '8977402135f4f28eb252473dc8ecf36f5b0253abd156c413bfae7886c6562e21' });
// "FTSystem/myapp/1.2.3 (hash:8977402135f4f28eb252473dc8ecf36f5b0253abd156c413bfae7886c6562e21)"
```

The `hash` option defaults to the value of `process.env.USER_AGENT_HASH` if present.

#### `libraries` option

If you pass in an options object with a `libraries` property (Array of strings - `string[]`), then library names and versions will be added based on what's found in the application's `node_modules` folder, e.g.

```js
buildUserAgent({ libraries: ['node-fetch'] });
// "FTSystem/myapp/1.2.3 (node-fetch/2.0.0; Node.js/22.13.1)"
```

If you pass in multiple libraries then they will be separated by semicolons (`;`). If a library with a given name cannot be found under `node_modules` then it will be excluded.

#### `urls` option

If you pass in an options object with a `urls` property (Array of strings - `string[]`), then these URLs will be added with a leading `+`, e.g.

```js
buildUserAgent({ urls: ['https://www.ft.com/'] });
// "FTSystem/myapp/1.2.3 (+https://www.ft.com/; Node.js/22.13.1)"
```

If you pass in multiple urls then they will be separated by semicolons (`;`).


## License

Licensed under the [MIT](LICENSE) license.<br/>
Copyright &copy; 2024, The Financial Times Ltd.

---
_Source: https://npm.io/package/@financial-times/user-agent · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._