Registry / http-networking / axios-proxy-builder

axios-proxy-builder

library0.1.2jsnpmunverified

axios-proxy-builder is a focused utility designed to generate Axios-compatible proxy configuration objects by interpreting standard HTTP/HTTPS proxy environment variables, including `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`. Currently at version 0.1.2, this package provides a single `configureProxy` function. Its `no-proxy` exclusion logic is notably inspired by the robust implementation found in the now-deprecated `request` library. This tool simplifies proxy integration for Axios in Node.js environments, particularly where proxy settings are managed via system environment variables. While it's in early development, indicated by its 0.x.x versioning, it offers a specific and streamlined solution. The release cadence is likely infrequent, driven by user feedback or minor enhancements rather than a fixed schedule. It differentiates itself from manually configuring Axios proxies by abstracting the parsing of common proxy environment variables, making it a 'set and forget' solution for many common proxy use cases.

http-networking devops

npm install axios-proxy-builder

github ↗package ↗

INSTALL

IMPORT

SIG · AXIOS-PROXY-BUILDE

axios-proxy-builder

http-networkingjavascriptv0.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

configureProxy

✓ import { configureProxy } from 'axios-proxy-builder';

✗ const configureProxy = require('axios-proxy-builder');

The library is primarily designed for ESM usage with TypeScript. While CommonJS `require` might work in some transpiled environments, native ESM import is the intended and safest approach.

Demonstrates how to configure standard HTTP proxy environment variables and then use `configureProxy` to apply the detected proxy settings to an Axios GET request.

import axios from 'axios'; import { configureProxy } from 'axios-proxy-builder'; // IMPORTANT: Set these environment variables before running the script // For example, in your shell: // export HTTP_PROXY="http://your.proxy.server:8080" // export NO_PROXY="localhost,127.0.0.1,api.example.com" // For HTTPS, also set HTTPS_PROXY. const targetUrl = 'https://api.ipify.org/?format=json'; // A public API to test IP async function makeProxiedRequest() { // Retrieve proxy configuration based on current environment variables const proxyConfig = configureProxy(targetUrl); try { console.log('Attempting request to:', targetUrl); if (proxyConfig) { console.log('Using proxy configuration:', proxyConfig); } else { console.log('No proxy configured via environment variables for this URL.'); } const response = await axios.get(targetUrl, { proxy: proxyConfig || false, // Pass the generated proxy object, or false if no proxy }); console.log('Response data:', response.data); // Should show the proxy's IP if configured console.log('Request successful!'); } catch (error: any) { if (axios.isAxiosError(error)) { console.error('Axios Error:', error.message); if (error.response) { console.error('Status:', error.response.status); console.error('Data:', error.response.data); } else if (error.request) { console.error('No response received:', error.request); } else { console.error('Error config:', error.config); } } else { console.error('Unexpected Error:', error); } } } // You would typically call this function in your application flow // For demonstration, we'll call it directly. makeProxiedRequest();

Debug

Known issues

gotchaThe package is in early development (version 0.1.2) and its API may not be stable. Users should be aware that breaking changes could occur in future minor or patch versions before a 1.0 release.

fix

Monitor GitHub repository for updates and breaking changes before upgrading. Consider pinning to exact versions in production.

affects: 0.x.x

gotchaThis utility relies heavily on standard environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`). Ensure these are correctly set and accessible in the Node.js process environment where `configureProxy` is executed. Misconfigured or missing variables will result in no proxy being applied or incorrect proxy behavior.

fix

Verify environment variables are properly defined for the Node.js process. On Linux/macOS, use `export VAR=value`; on Windows, use `set VAR=value` or configure system-wide. Always check `process.env` in your application if unsure.

affects: >=0.1.0

gotchaThe `NO_PROXY` environment variable expects a comma-separated list of hostnames or IPs for which the proxy should not be used. Incorrect patterns (e.g., wildcards not explicitly supported, or incorrect domain matching) can lead to unintended proxying or failure to proxy when expected.

fix

Carefully review the `NO_PROXY` documentation (often following `request` library's logic). Test `configureProxy` with various `NO_PROXY` values to ensure desired behavior. Ensure full domain names are listed where appropriate, e.g., `example.com` not just `example`.

affects: >=0.1.0

gotchaAxios's built-in `proxy` option only supports HTTP/HTTPS proxies. For SOCKS proxies, an external agent like `socks-proxy-agent` must be used, which `axios-proxy-builder` does not directly integrate.

fix

If SOCKS proxies are required, you will need to manually configure Axios with an appropriate agent (e.g., `httpsAgent` or `httpAgent`) and set `proxy: false` to prevent Axios from automatically using environment variables for HTTP/HTTPS proxies. `axios-proxy-builder` is not suitable for SOCKS proxy configuration.

affects: >=0.1.0

Errors

Common errors & fixes

AxiosError: Network Error

This generic error often indicates that Axios could not establish a connection to the target server or the proxy. Common causes include an unreachable proxy server, incorrect proxy credentials (if embedded in URL via env vars), or network connectivity issues between your application and the proxy/target.

fix

1. Verify your `HTTP_PROXY`/`HTTPS_PROXY` environment variables are correctly formatted and point to a running, accessible proxy server. 2. Check network connectivity (e.g., `ping` or `curl`) from your application's host to the proxy server. 3. Ensure any required proxy authentication (if supported via URL in env var) is correct.

Error: Invalid proxy protocol: null

This error typically occurs if the `HTTP_PROXY` or `HTTPS_PROXY` environment variable is malformed and does not contain a valid protocol (e.g., `http://` or `https://`). Axios expects the `protocol` property in the proxy configuration object to be 'http' or 'https'.

fix

Review your proxy environment variables. Ensure they start with a valid protocol, e.g., `export HTTP_PROXY="http://proxy.example.com:8080"`.

ReferenceError: axios is not defined

This package generates a proxy *object* for Axios, but it does not automatically install or import Axios itself. This error means Axios has not been imported or installed in your project.

fix

Install Axios (`npm install axios`) and ensure you import it in your code using `import axios from 'axios';` or `const axios = require('axios');`.

407 Proxy Authentication Required

Your proxy server requires authentication (username and password) which was not provided or was incorrect. While `axios-proxy-builder` can parse credentials embedded in the proxy URL (e.g., `http://user:pass@host:port`), direct support for separate `auth` objects in the environment variables is not explicit.

fix

If your proxy requires authentication, include the username and password directly in the proxy environment variable URL (e.g., `http://user:pass@proxy.example.com:8080`). Ensure these credentials are correct.

Upgrade

Version history

0.1.2latest on npm

Audit

Dependencies

axiosrequiredThis utility builds proxy configuration objects specifically for the Axios HTTP client. Axios is a peer/runtime dependency for the generated configuration to be useful.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/farawaysouthwest/axios-proxy-builder ↗

packagehttps://www.npmjs.com/package/axios-proxy-builder ↗