How to Use Geonode Proxies with Node.js

Setup

Generate an endpoint in the Geonode dashboard and export GEONODE_HOST, GEONODE_PORT, GEONODE_USER and GEONODE_PASS. Then build proxy URLs in one place:

export function geonodeUrl(country) {
  const user = process.env.GEONODE_USER + (country ? `-country-${country}` : '');
  const pass = encodeURIComponent(process.env.GEONODE_PASS);
  return `http://${user}:${pass}@${process.env.GEONODE_HOST}:${process.env.GEONODE_PORT}`;
}

The -country- suffix follows the pattern in Geonode's documentation; use your dashboard's exact format.

Native fetch with undici

Node's built-in fetch is powered by undici. Pass a ProxyAgent as the dispatcher:

import { ProxyAgent, fetch } from 'undici';
import { geonodeUrl } from './geonode.js';

const dispatcher = new ProxyAgent(geonodeUrl('us'));
const res = await fetch('https://api.ipify.org', { dispatcher });
console.log(await res.text());

A ProxyAgent keeps connections open, so requests through the same agent may reuse the same exit. Create a new agent when you need a fresh IP from a rotating endpoint.

Environment variable proxies

Recent Node.js versions can make built-in HTTP clients honour standard HTTP_PROXY and HTTPS_PROXY environment variables when enabled. That's convenient for tools you don't control, but explicit agents are clearer for scrapers where different requests need different exits. Check the Node documentation for your version.

axios

import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';
import { geonodeUrl } from './geonode.js';

const agent = new HttpsProxyAgent(geonodeUrl('gb'));
const { data } = await axios.get('https://api.ipify.org', { httpsAgent: agent, proxy: false });
console.log(data);

Set proxy: false so axios doesn't apply its own proxy handling on top of the agent.

Sticky sessions

With a sticky Geonode endpoint, reuse one agent for all requests in a flow so cookies and IP stay consistent. Store cookies with a cookie jar library if the site needs them.

SOCKS5

Use socks-proxy-agent with a socks5h:// URL (DNS through the proxy) and check the dashboard for the SOCKS port:

import { SocksProxyAgent } from 'socks-proxy-agent';
const agent = new SocksProxyAgent(geonodeUrl('de').replace('http://', 'socks5h://'));

Concurrency

Use a small concurrency limiter (for example p-limit) and cap requests per domain:

import pLimit from 'p-limit';
const limit = pLimit(20);
const results = await Promise.all(urls.map((u) => limit(() => fetchPage(u))));

Errors

Choosing the right Geonode product for Node.js jobs

Node.js is used for everything from small scripts to large crawlers and API backends, so the right proxy product depends on the job rather than the language.

A common pattern in Node.js services is a small "proxy factory" module that returns the right agent for a domain: a datacenter agent for most targets, a residential agent for a configured list of protected domains, and a sticky agent when a caller asks for a session. Keeping that logic in one module means the rest of the codebase never deals with proxy URLs directly, and switching products or providers is a one-file change.

Production habits for Node.js proxy code

• Set timeouts everywhere. Both undici and axios can wait a long time by default. A dead exit should fail in tens of seconds, not minutes.
• Close or reuse agents deliberately. Creating thousands of agents without closing them leaks sockets; reusing one agent for everything keeps you on the same exits. Create agents per job and close them when the job ends.
• Check content, not status. Many blocks return 200 with a challenge page. Look for an element you expect.
• Log outcomes per domain: success, block, timeout, proxy error. That's how you notice a target moving from "works on datacenter" to "needs residential".
• Keep credentials in environment variables and never log full proxy URLs, which contain passwords.
• Back off on failure, with jitter, and cap retries so a blocked target can't burn your bandwidth.

These habits matter more than which HTTP client you choose. For more on rotation design, see proxy rotation strategies, and for broader scraping practice, Geonode for web scraping.

Testing your setup

Before using a Geonode endpoint in production code, confirm it from Node with a short script that requests an IP echo service three times through a rotating endpoint and three times through a sticky one. You should see three different IPs for rotating and one repeated IP for sticky. If you see your own IP, the agent isn't being applied; if you see errors, test the same endpoint with cURL to separate code problems from endpoint problems. See Geonode with cURL.

Run that script in CI too, against a test sub-user with a small traffic limit, so dependency upgrades that change proxy behaviour are caught before deployment.

FAQ

Does Node's fetch support proxies?

Yes, through undici's ProxyAgent passed as dispatcher, or through environment variable support in recent Node versions.

How do I get a new IP per request?

Use a rotating endpoint and a new agent per request or per job.

axios or fetch?

Either. fetch with undici has no extra dependencies; axios is convenient if your codebase already uses it.

Can I use Geonode with Puppeteer from Node?

Yes. See Geonode with Puppeteer.