Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
pi0 authored Dec 23, 2023
1 parent f6dd60d commit 0c884a2
Showing 1 changed file with 32 additions and 27 deletions.
59 changes: 32 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,33 +80,6 @@ const {
} = require("node-fetch-native");
```

## Proxy support

Node.js has no built-in support for HTTP Proxies for fetch (see [nodejs/undici#1650](https://github.com/nodejs/undici/issues/1650) and [nodejs/node#8381](https://github.com/nodejs/node/issues/8381))

This package bundles a compact and simple proxy supported for both Node.js versions without native fetch using [HTTP Agent](https://github.com/TooTallNate/proxy-agents/tree/main/packages/proxy-agent) and versions with native fetch using [Undici Proxy Agent](https://undici.nodejs.org/#/docs/api/ProxyAgent).

**Usage:**

```ts
import { fetch } from "node-fetch-native"; // or use global fetch
import { createProxy } from "node-fetch-native/proxy";

const proxy = createProxy(); // Uses HTTPS_PROXY or HTTP_PROXY by default

const proxy = createProxy({ url: "http://localhost:8080" });

await fetch("https://google.com", {
...proxy,
});
```

`createProxy` returns an object with `agent` for older Node.js versions and `dispatcher` keys for newer Node.js versions with Undici and native fetch.

If no `url` option is provided, `HTTPS_PROXY` or `HTTP_PROXY` values will be used, and if they also are not set, both `agent` and `dispatcher` values will be undefined.

**Note:** Using export conditions, this utility works in Node.js and for other runtimes, it will simply return a stubbed version as most of the other runtimes now support HTTP proxy out of the box!

## Force using non-native version

Sometimes you want to explicitly use none native (`node-fetch`) implementation of `fetch` in case of issues with the native/polyfill version of `globalThis.fetch` with Node.js or runtime environment.
Expand All @@ -132,6 +105,38 @@ require("node-fetch-native/polyfill");
// You can now use fetch() without any import!
```

## Proxy Support

Node.js has no built-in support for HTTP Proxies for fetch (see [nodejs/undici#1650](https://github.com/nodejs/undici/issues/1650) and [nodejs/node#8381](https://github.com/nodejs/node/issues/8381))

This package bundles a compact and simple proxy supported for both Node.js versions without native fetch using [HTTP Agent](https://github.com/TooTallNate/proxy-agents/tree/main/packages/proxy-agent) and versions with native fetch using [Undici Proxy Agent](https://undici.nodejs.org/#/docs/api/ProxyAgent).

**Usage:**

```ts
import { fetch } from "node-fetch-native"; // or use global fetch
import { createProxy } from "node-fetch-native/proxy";

// Uses HTTPS_PROXY or HTTP_PROXY environment variables
const proxy = createProxy();

// const proxy = createProxy({ url: "http://localhost:8080" });

await fetch("https://google.com", {
...proxy,
});
```

`createProxy` returns an object with `agent` for older Node.js versions and `dispatcher` keys for newer Node.js versions with Undici and native fetch.

If no `url` option is provided, `HTTPS_PROXY` or `HTTP_PROXY` values will be used, and if they also are not set, both `agent` and `dispatcher` values will be undefined.

> [!NOTE]
> Using export conditions, this utility works in Node.js and for other runtimes, it will simply return a stubbed version as most of the other runtimes now support HTTP proxy out of the box!
> [!NOTE]
> Proxy support is under development. Check [unjs/node-fetch-native#107](https://github.com/unjs/node-fetch-native/issues/107) for the roadmap and contributing!
## Alias to `node-fetch`

Using this method, you can ensure all project dependencies and usages of `node-fetch` can benefit from improved `node-fetch-native` and won't conflict between `node-fetch@2` and `node-fetch@3`.
Expand Down

0 comments on commit 0c884a2

Please sign in to comment.