Node.js Integration

NinjasProxy supports all major Node.js HTTP clients via the standard https-proxy-agent and socks-proxy-agent packages. TypeScript types are included throughout.

Install shared deps once: npm install https-proxy-agent socks-proxy-agent. Each library section lists its own additional peer dependency.

node-fetch

// npm install node-fetch https-proxy-agent
import fetch from 'node-fetch'
import { HttpsProxyAgent } from 'https-proxy-agent'

const PROXY_URL = 'http://USERNAME:API_KEY@r.ninjasproxy.com:8080'
const agent     = new HttpsProxyAgent(PROXY_URL)

const res  = await fetch('https://api.ipify.org?format=json', { agent })
const data = await res.json() as { ip: string }
console.log('Exit IP:', data.ip)

// Geo-targeted request
const geoAgent = new HttpsProxyAgent(
  'http://USERNAME-country-US-city-NewYork:API_KEY@r.ninjasproxy.com:8080'
)
const geoRes = await fetch('https://api.ipify.org?format=json', { agent: geoAgent })
console.log('NYC IP:', (await geoRes.json() as { ip: string }).ip)

axios

// npm install axios https-proxy-agent
import axios from 'axios'
import { HttpsProxyAgent } from 'https-proxy-agent'

const PROXY_URL   = 'http://USERNAME:API_KEY@r.ninjasproxy.com:8080'
const httpsAgent  = new HttpsProxyAgent(PROXY_URL)

// ── Single request ───────────────────────────────────────────────
const { data } = await axios.get<{ ip: string }>(
  'https://api.ipify.org?format=json',
  { httpsAgent, httpAgent: httpsAgent }
)
console.log('Exit IP:', data.ip)

// ── Reusable axios instance ──────────────────────────────────────
const proxyAxios = axios.create({
  httpsAgent,
  httpAgent: httpsAgent,
  timeout: 30_000,
  headers: {
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
  },
})

const res = await proxyAxios.get('https://httpbin.org/ip')
console.log(res.data)

// ── POST with JSON ───────────────────────────────────────────────
const postRes = await proxyAxios.post(
  'https://httpbin.org/post',
  { query: 'test', page: 1 },
  { headers: { 'Content-Type': 'application/json' } }
)
console.log(postRes.status, postRes.data.json)

got

// npm install got https-proxy-agent
import got from 'got'
import { HttpsProxyAgent } from 'https-proxy-agent'

const agent = {
  https: new HttpsProxyAgent('http://USERNAME:API_KEY@r.ninjasproxy.com:8080'),
}

// ── Basic GET ────────────────────────────────────────────────────
const body = await got('https://api.ipify.org?format=json', { agent }).json<{ ip: string }>()
console.log('Exit IP:', body.ip)

// ── got with retry ───────────────────────────────────────────────
const retryClient = got.extend({
  agent,
  timeout: { request: 30_000 },
  retry: {
    limit: 4,
    methods: ['GET', 'POST'],
    statusCodes: [500, 502, 503, 504],
    calculateDelay: ({ attemptCount }) => Math.min(2 ** attemptCount * 1_000, 30_000),
  },
})

const data = await retryClient.get('https://httpbin.org/ip').json()
console.log(data)

Playwright

// npm install playwright @playwright/test
import { chromium } from 'playwright'

const browser = await chromium.launch({
  proxy: {
    server:   'http://r.ninjasproxy.com:8080',
    username: 'USERNAME',
    password: 'API_KEY',
  },
  headless: true,
})

const context = await browser.newContext({
  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
  locale: 'en-US',
})

const page = await context.newPage()
await page.goto('https://api.ipify.org?format=json')
console.log('Exit IP:', await page.textContent('body'))

// Screenshot via proxy
await page.goto('https://example.com')
await page.screenshot({ path: 'screenshot.png' })

await browser.close()

Puppeteer

// npm install puppeteer
import puppeteer from 'puppeteer'

const browser = await puppeteer.launch({
  args: ['--proxy-server=http://r.ninjasproxy.com:8080'],
  headless: 'new',
})

const page = await browser.newPage()

// Authenticate for credential-based auth
await page.authenticate({ username: 'USERNAME', password: 'API_KEY' })

await page.goto('https://api.ipify.org?format=json', { waitUntil: 'networkidle2' })
const body = await page.evaluate(() => document.body.innerText)
console.log('Exit IP:', body)

await browser.close()

TypeScript Types

// types/proxy.ts
export interface ProxyConfig {
  host:     string
  port:     number
  username: string
  apiKey:   string
}

export interface TargetingOptions {
  country?:  string   // ISO 3166-1 alpha-2, e.g. 'US'
  city?:     string   // CamelCase, e.g. 'NewYork'
  carrier?:  string   // Mobile carrier slug, e.g. 'att'
  sessionId?: string  // For sticky sessions
}

export function buildProxyUrl(
  config: ProxyConfig,
  targeting: TargetingOptions = {}
): string {
  let user = config.username
  if (targeting.country)   user += `-country-${targeting.country}`
  if (targeting.city)      user += `-city-${targeting.city}`
  if (targeting.carrier)   user += `-carrier-${targeting.carrier}`
  if (targeting.sessionId) user += `-session-${targeting.sessionId}`
  return `http://${user}:${config.apiKey}@${config.host}:${config.port}`
}

// Usage
const config: ProxyConfig = {
  host:     'r.ninjasproxy.com',
  port:     8080,
  username: process.env.NINJASPROXY_USER!,
  apiKey:   process.env.NINJASPROXY_KEY!,
}

const url = buildProxyUrl(config, { country: 'US', city: 'Chicago', sessionId: 'run1' })
// http://user-country-US-city-Chicago-session-run1:key@r.ninjasproxy.com:8080

Async Iteration Over Multiple URLs

// Bounded concurrency with p-limit
// npm install p-limit axios https-proxy-agent
import pLimit from 'p-limit'
import axios   from 'axios'
import { HttpsProxyAgent } from 'https-proxy-agent'

const CONCURRENCY = 50  // Stay below your plan limit

const agent = new HttpsProxyAgent('http://USERNAME:API_KEY@r.ninjasproxy.com:8080')
const client = axios.create({ httpsAgent: agent, httpAgent: agent, timeout: 30_000 })
const limit  = pLimit(CONCURRENCY)

async function fetchAll(urls: string[]): Promise<Array<{ url: string; status: number; bytes: number }>> {
  const tasks = urls.map(url =>
    limit(async () => {
      try {
        const res = await client.get(url)
        return { url, status: res.status, bytes: JSON.stringify(res.data).length }
      } catch (err: any) {
        return { url, status: err?.response?.status ?? 0, bytes: 0 }
      }
    })
  )
  return Promise.all(tasks)
}

const results = await fetchAll([
  'https://api.ipify.org?format=json',
  'https://httpbin.org/ip',
  // ... thousands more
])

results.forEach(r => console.log(r.url, r.status, r.bytes))

Next Steps