fetch

Node.js 18+ ships with fetch powered by a stripped-down undici. It does not support proxies out of the box to compliant to the WHATWG Fetch spec.

Install the full undici library to get access to the ProxyAgent class, which implements the necessary proxy support. You can choose to route all fetch calls through the proxy by setting a global dispatcher, or specify the agent on a per-request basis.

Prerequisites

A Rayley account with a Proxy Token (rpt_*). Create one in the dashboard.

Installation

npm install undici

undici already ships with Node.js, but installing it explicitly lets you import ProxyAgent.

Quick start

Set a global ProxyAgent dispatcher to route all fetch calls through your static IP address. Pass the token via the token option on the agent:

proxy-all.mjs

import { ProxyAgent, setGlobalDispatcher } from 'undici';

const proxyAgent = new ProxyAgent({
  uri: 'https://proxy.rayley.com',
  token: 'Bearer rpt_your_token_here',
});

setGlobalDispatcher(proxyAgent);

// All fetch requests now go through the proxy
const response = await fetch('https://api.example.com/data');
const data = await response.json();
console.log(data);

Using this method, even libraries that use fetch internally automatically use Rayley.

Use a static IP Address for specific requests only

Import fetch from undici directly and pass a dispatcher option to control which requests go through the proxy:

proxy-selective.mjs

import { ProxyAgent, fetch } from 'undici';

const proxyAgent = new ProxyAgent({
  uri: 'https://proxy.rayley.com',
  token: 'Bearer rpt_your_token_here',
});

// This request uses your static IP Address
const response = await fetch('https://api.example.com/data', {
  dispatcher: proxyAgent,
});
const data = await response.json();
console.log(data);

// This request goes directly to the destination without using Rayley
const response2 = await fetch('https://api.example.com/other-data');
const data2 = await response2.json();
console.log(data2);

Full example

Below is a script you can use to test your Proxy Token. It reads the token from the RAYLEY_TOKEN environment variable and takes an optional URL argument (defaulting to https://example.com) to make a request using your static IP address.

example.mjs

import { ProxyAgent, setGlobalDispatcher } from 'undici';

const proxyToken = process.env.RAYLEY_TOKEN;
const targetUrl = process.argv[2] || 'https://example.com/';

if (!proxyToken) {
  console.error('Set RAYLEY_TOKEN to your Proxy Token.');
  process.exit(1);
}

const proxyAgent = new ProxyAgent({
  uri: 'https://proxy.rayley.com',
  token: `Bearer ${proxyToken}`,
});

setGlobalDispatcher(proxyAgent);

try {
  const response = await fetch(targetUrl);

  if (response.status === 407) {
    throw new Error('Authentication failed. Check your RAYLEY_TOKEN.');
  }

  const data = await response.json();
  console.log(`Status: ${response.status}`);
  console.log(JSON.stringify(data, null, 2));
} catch (error) {
  console.error('Request failed:', error.message);
  process.exit(1);
}

Run it:

RAYLEY_TOKEN=rpt_your_token node example.mjs https://example.com/