{"id":16040,"library":"global-tunnel-ng","title":"Global HTTP & HTTPS Tunneling","description":"global-tunnel-ng is a utility that globally configures Node.js's built-in `http` and `https` agents to route all outgoing network traffic through an upstream HTTP proxy. It works transparently for modules that utilize Node's default `http.request()` method and popular libraries like `request`. The current stable version is 2.7.1, published in November 2018. The package focuses on transparent global proxying, allowing developers to set a proxy once for an entire application without modifying individual HTTP client calls. It supports both `CONNECT` tunneling for HTTPS (and optionally HTTP) and absolute-URI request methods, accommodating various proxy configurations. Its primary differentiator is its low-level global interception of Node.js's native networking stack. For modern Node.js versions (v10+), `global-agent` is often recommended as a more actively maintained alternative.","status":"maintenance","version":"2.7.1","language":"javascript","source_language":"en","source_url":"https://github.com/np-maintain/global-tunnel","tags":["javascript","http","https","tunnel","global"],"install":[{"cmd":"npm install global-tunnel-ng","lang":"bash","label":"npm"},{"cmd":"yarn add global-tunnel-ng","lang":"bash","label":"yarn"},{"cmd":"pnpm add global-tunnel-ng","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for managing HTTP proxy tunneling agents; internal to global-tunnel-ng's operation.","package":"tunnel-agent","optional":false}],"imports":[{"note":"This package is CommonJS-only and does not support ES Modules directly. Use `require`.","wrong":"import globalTunnel from 'global-tunnel-ng';","symbol":"globalTunnel","correct":"const globalTunnel = require('global-tunnel-ng');"},{"note":"The `initialize` method configures the global HTTP/HTTPS agents. It should be called once early in your application lifecycle.","symbol":"initialize","correct":"globalTunnel.initialize({ /* options */ });"},{"note":"Call `end` to tear down the global agent and restore Node.js's default agents. Active connections complete first.","symbol":"end","correct":"globalTunnel.end();"}],"quickstart":{"code":"const globalTunnel = require('global-tunnel-ng');\n\n// Configure a global HTTP/HTTPS proxy\nglobalTunnel.initialize({\n  host: '10.0.0.10',\n  port: 8080,\n  proxyAuth: process.env.PROXY_USER_PASS ?? '', // optional authentication as 'userId:password'\n  sockets: 50, // optional pool size for each http and https agent\n  // For a proxy requiring absolute URIs for HTTP/HTTPS:\n  // connect: 'neither',\n  // For a proxy requiring CONNECT for both HTTP/HTTPS:\n  // connect: 'both',\n  // If the proxy itself speaks HTTPS:\n  // protocol: 'https:'\n});\n\n// Example of an HTTP request that will go through the configured proxy\nconst http = require('http');\n\nhttp.get('http://example.com/data', (res) => {\n  console.log(`Status: ${res.statusCode}`);\n  res.setEncoding('utf8');\n  let rawData = '';\n  res.on('data', (chunk) => { rawData += chunk; });\n  res.on('end', () => {\n    try {\n      console.log('Received data:', rawData.substring(0, 100) + '...');\n    } catch (e) {\n      console.error(e.message);\n    }\n    globalTunnel.end(); // Clean up the proxy configuration\n  });\n}).on('error', (e) => {\n  console.error(`Request error: ${e.message}`);\n  globalTunnel.end();\n});","lang":"javascript","description":"This quickstart initializes a global HTTP/HTTPS proxy using `global-tunnel-ng` and demonstrates how a standard Node.js `http.get` request automatically routes through it. It also shows how to tear down the proxy."},"warnings":[{"fix":"For Node.js v11.6.0+, migrate to `global-agent` (e.g., `import 'global-agent/bootstrap';` and set `GLOBAL_AGENT_HTTP_PROXY` environment variable) or use a library-specific proxy configuration.","message":"`global-tunnel-ng` is known to be broken and incompatible with Node.js versions 11.6.0 and above. It relies on internal Node.js mechanisms that changed in newer versions. For modern Node.js environments (v10+), consider using `global-agent` as an actively maintained alternative.","severity":"breaking","affected_versions":">=11.6.0"},{"fix":"Consult your proxy documentation. Use `connect: 'neither'` for proxies expecting absolute URIs for all requests, or `connect: 'both'` if the proxy expects `CONNECT` for both HTTP and HTTPS requests. The default `connect: 'https'` is suitable for many standard HTTP proxies.","message":"The `connect` option within `globalTunnel.initialize()` is crucial and often misconfigured. It controls whether the `CONNECT` method is used for HTTP, HTTPS, or neither. The default is `https`, meaning `CONNECT` is only used for HTTPS. Incorrect configuration for your proxy type can lead to connection failures.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure `global-tunnel-ng` is initialized early in your application. If other modules explicitly define an `agent` option in their `http.request` calls, they will bypass `global-tunnel-ng`'s configuration. Consider using library-specific proxy settings or an alternative like `global-agent` which offers more explicit control and compatibility strategies.","message":"Modifying Node.js's global `http.globalAgent` and `https.globalAgent` can conflict with other libraries or custom code that also attempt to manage these global agents or instantiate their own specific `Agent` instances. This can lead to unexpected proxy bypasses or errors.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"For new projects or applications running on Node.js v10+, consider migrating to `global-agent`. It offers similar global proxying capabilities with better support for newer Node.js features and environment variable configuration.","message":"This package is considered for 'legacy Node.js versions' and is under `np-maintain`, indicating limited active development for new Node.js features or bug fixes. For modern applications and Node.js versions (v10 and above), the `global-agent` package is a recommended, more actively maintained alternative.","severity":"deprecated","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify the `host`, `port`, and `proxyAuth` options in `globalTunnel.initialize()`. Check network connectivity to the proxy. Ensure the proxy supports the `CONNECT` method for the requested protocol (HTTP/HTTPS) as configured by the `connect` option.","cause":"The proxy server rejected the CONNECT request, often due to incorrect proxy address/port, authentication failure, or network firewall rules.","error":"Error: tunneling socket could not be established"},{"fix":"Change your import statement to `const globalTunnel = require('global-tunnel-ng');` as `global-tunnel-ng` is a CommonJS module.","cause":"This typically occurs when attempting to use an ES module `import` syntax (`import globalTunnel from 'global-tunnel-ng';`) instead of the CommonJS `require` syntax (`const globalTunnel = require('global-tunnel-ng');`).","error":"TypeError: globalTunnel.initialize is not a function"},{"fix":"1) Check Node.js version; if >=11.6.0, switch to `global-agent`. 2) Ensure `global-tunnel-ng` is initialized before other modules that might manage agents. Check if affected modules allow configuring an explicit agent to `null` or `undefined` to force use of the global agent. 3) Review and adjust the `connect` option. 4) Double-check `host`, `port`, and `proxyAuth`.","cause":"This can happen if: 1) The Node.js version is incompatible (>=11.6.0). 2) Another module explicitly sets an `agent` option on its HTTP/HTTPS requests, bypassing the global agent. 3) The `connect` option in `initialize` is misconfigured for your proxy type. 4) The proxy configuration (host, port) is incorrect.","error":"Requests are not going through the configured proxy."}],"ecosystem":"npm"}