# aws-xray-sdk-fetch

> AWS X-Ray plugin for node-fetch

Latest version **3.12.0** (published 2025-11-20) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install aws-xray-sdk-fetch
pnpm add aws-xray-sdk-fetch
yarn add aws-xray-sdk-fetch
bun add aws-xray-sdk-fetch
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 3.12.0 |
| Published | 2025-11-20 |
| First published | 2024-03-25 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >= 14.x |
| Dependencies | 1 |
| Unpacked size | 23.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 280 |
| Author | Amazon Web Services |
| Maintainers | awsxray |
| Keywords | amazon, api, aws, fetch, node-fetch, xray, x-ray, x ray |

## Links

- npm: https://www.npmjs.com/package/aws-xray-sdk-fetch
- Repository: https://github.com/aws/aws-xray-sdk-node.git#master
- Homepage: https://github.com/aws/aws-xray-sdk-node/tree/master#readme
- Issues: https://github.com/aws/aws-xray-sdk-node/issues
- npm.io page: https://npm.io/package/aws-xray-sdk-fetch

## Dependencies (1)

- [tsd](https://npm.io/package/tsd.md) ^0.28.1

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 3.12.0 (latest) — 2025-11-20
- 3.11.0 — 2025-10-15
- 3.10.3 — 2025-01-24
- 3.10.2 — 2024-11-12
- 3.10.1 — 2024-09-19
- 3.10.0 — 2024-09-09
- 3.9.0 — 2024-06-10
- 3.8.0 — 2024-06-06
- 3.7.0 — 2024-06-05
- 3.6.0 — 2024-03-25

## README

# fetch-xray

A patcher for AWSXRay to support fetch, implemented via either the [node-fetch module](https://www.npmjs.com/package/node-fetch) or the built-in 
global fetch support starting with [NodeJS 18](https://nodejs.org/en/blog/announcements/v18-release-announce).

## Usage

```js
const { captureFetchGlobal } = require('aws-xray-sdk-fetch');

// To use globally defined fetch (available in NodeJS 18+)
const fetch = captureFetchGlobal();
const result = await fetch('https://foo.com');

// To use node-fetch module
const { captureFetchModule } = require('aws-xray-sdk-fetch');
const fetchModule = require('node-fetch');
const fetch = captureFetchModule(fetchModule); // Note, first parameter *must* be the node-fetch module
const result = await fetch('https://foo.com');
```

There are two optional parameters you can pass when calling `captureFetchGlobal` / `captureFetchModule`:

* **downstreamXRayEnabled**: when True, adds a "traced:true" property to the subsegment so the AWS X-Ray service expects a corresponding segment from the downstream service (default = False)
* **subsegmentCallback**: a callback that is called with the subsegment, the fetch request, the fetch response and any error issued, allowing custom annotations and metadata to be added

TypeScript bindings for the capture functions are included.

## Testing

Unit and integration tests can be run using `npm run test`.  Typings file tess can be run using `npm run test-d`.

## Errata

1. This package CommonJS to conform with the rest of the AWSXRay codebase.  As such, it is incompatible with node-fetch 3, which is ESM only.  As such, it is written
to be compatible with [node-fetch version 2](https://www.npmjs.com/package/node-fetch#CommonJS), which should still receive critical fixes.  If you are using global
fetch (available in NodeJS 18+) then this isn't an issue for you.

2. This package is designed working under the assumption that the NodeJS implementation of fetch is compatible with node-fetch, albeit with its own separate, 
built-in typings.  If NodeJS takes fetch in a different direction (breaks compatibility) then that would most likely break this package.  There is no indication that
I could find that this will happen, but throwing it out there "just in case".

## Contributors

- [Jason Terando](https://github.com/jasonterando)
- [Bernd Fuhrmann](https://github.com/berndfuhrmann)

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