Use Dev Proxy with Node.js applications

At a glance
Goal: Configure Node.js applications to use Dev Proxy
Time: 10 minutes
Prerequisites: Set up Dev Proxy, Node.js application

How you route Node.js requests through Dev Proxy depends on your Node.js version and the library you use to make HTTP requests. Recent Node.js versions can route the native fetch API and the http and https modules through a proxy defined in environment variables. For older Node.js versions and for other libraries, you configure the proxy in your code, or use the global-agent package to enable proxy support with minimal code changes.

Whichever approach you use, Node.js must trust the Dev Proxy root certificate to make HTTPS requests through Dev Proxy. For more information, see Trust the Dev Proxy certificate.

Trust the Dev Proxy certificate

Node.js doesn't use the operating system certificate store by default, so it doesn't trust the Dev Proxy root certificate even after you trust it on your machine. Instead of disabling certificate validation, add the Dev Proxy root certificate to the certificates that Node.js trusts using the NODE_EXTRA_CA_CERTS environment variable.

NODE_EXTRA_CA_CERTS requires a certificate in the PEM format. While Dev Proxy is running, get the API token using devproxy api token, and download the root certificate in the PEM format using the Dev Proxy API:

TOKEN=$(devproxy api token)
curl -H "Authorization: Bearer $TOKEN" -o dev-proxy-ca.pem "http://127.0.0.1:8897/proxy/rootCertificate?format=crt"

If you use PowerShell, run:

$token = devproxy api token
Invoke-WebRequest -Headers @{ Authorization = "Bearer $token" } -OutFile dev-proxy-ca.pem -Uri "http://127.0.0.1:8897/proxy/rootCertificate?format=crt"

Then, point the NODE_EXTRA_CA_CERTS environment variable to the downloaded file when you start your app:

NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js

Node.js reads NODE_EXTRA_CA_CERTS only when the process starts, so you can't set it from your code. Each Dev Proxy installation uses its own root certificate. If you recreate the certificate, for example using devproxy cert remove and devproxy cert ensure, download it again.

Native Node.js fetch API

Starting with Node.js v24.0.0 and v22.21.0, the native fetch API can use the proxy defined in the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables. Starting with Node.js v24.5.0 and v22.21.0, the same applies to the http and https modules. Node.js ignores these variables unless you enable proxy support by setting the NODE_USE_ENV_PROXY environment variable to 1 or by starting Node.js with the --use-env-proxy flag.

You don't need to change your code to use Dev Proxy with the native fetch API:

(async () => {
  const result = await fetch('https://jsonplaceholder.typicode.com/posts');
  const jsonResult = await result.json();
  console.log(JSON.stringify(jsonResult, null, 2));
})();

When starting your app, enable proxy support, specify Dev Proxy as the proxy, and trust the Dev Proxy root certificate:

NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://127.0.0.1:8000 HTTP_PROXY=http://127.0.0.1:8000 NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js

Alternatively, use the --use-env-proxy flag instead of the NODE_USE_ENV_PROXY environment variable:

HTTPS_PROXY=http://127.0.0.1:8000 HTTP_PROXY=http://127.0.0.1:8000 NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node --use-env-proxy index.js

Use the native fetch API with older Node.js versions

If you use a Node.js version that doesn't support NODE_USE_ENV_PROXY, use the EnvHttpProxyAgent from the undici package, which implements the native fetch API in Node.js. EnvHttpProxyAgent reads the proxy from the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables. Set it as the global dispatcher at the start of your app:

import { EnvHttpProxyAgent, setGlobalDispatcher } from 'undici';
setGlobalDispatcher(new EnvHttpProxyAgent());

(async () => {
  const result = await fetch('https://jsonplaceholder.typicode.com/posts');
  const jsonResult = await result.json();
  console.log(JSON.stringify(jsonResult, null, 2));
})();

When starting your app, specify Dev Proxy as the proxy and trust the Dev Proxy root certificate:

HTTPS_PROXY=http://127.0.0.1:8000 HTTP_PROXY=http://127.0.0.1:8000 NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.mjs

global-agent

global-agent is a popular library that provides a global HTTP/HTTPS agent for Node.js. It allows you to specify the proxy using environment variables. The benefit of using global-agent is that you don't need to change how you issue HTTP requests in your application to use Dev Proxy.

Here's an example of how you can use global-agent in a Node.js application that uses node-fetch:

import fetch from 'node-fetch';
import { bootstrap } from 'global-agent';
bootstrap();

(async () => {
  const result = await fetch('https://jsonplaceholder.typicode.com/posts');
  const jsonResult = await result.json();
  console.log(JSON.stringify(jsonResult, null, 2));
})();

Here's how you can use global-agent with Node.js and the standard https module:

const https = require('https');
const globalAgent = require('global-agent');
globalAgent.bootstrap();

https.get('https://jsonplaceholder.typicode.com/posts', (resp) => {
  let data = '';
  resp.on('data', (d) => {
    data += d;
  });
  resp.on('end', () => {
    console.log(JSON.parse(data));
  });
  resp.on('error', (err) => {
    console.error(err);
  });
});

When starting your application, specify the proxy using the GLOBAL_AGENT_HTTP_PROXY environment variable and trust the Dev Proxy root certificate.

NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8000 node global-node-fetch.mjs

node-fetch

node-fetch is a popular library that provides a fetch implementation for Node.js. node-fetch doesn't support specifying the proxy using environment variables. Instead, you need to create a custom agent and pass it to the fetch method.

Here's an example of how you can use node-fetch with Dev Proxy by defining an agent using the https-proxy-agent package.

const fetch = require('node-fetch');
const { HttpsProxyAgent } = require('https-proxy-agent');

(async () => {
  // Create a custom agent pointing to Dev Proxy
  const agent = new HttpsProxyAgent('http://127.0.0.1:8000');
  // Pass the agent to the fetch method
  const result = await fetch('https://jsonplaceholder.typicode.com/posts', { agent });
  const jsonResult = await result.json();
  console.log(JSON.stringify(jsonResult, null, 2));
})();

When starting your app, trust the Dev Proxy root certificate:

NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js

Axios

Axios is another popular library for making HTTP requests in Node.js. Axios allows you to specify the proxy using environment variables or specify the agent directly in the request configuration.

Use Axios and Dev Proxy with environment variables

When you use Dev Proxy with Axios and specify the proxy using environment variables, you don't need to change your code. All you need to do is to set the https_proxy environment variable and Axios uses it to make requests.

import axios from 'axios';

(async () => {
  const result = await axios.get('https://jsonplaceholder.typicode.com/posts');
  const response = result.data;
  console.log(JSON.stringify(response, null, 2));
})();

Specify the https_proxy environment variable either globally or when starting your app, and trust the Dev Proxy root certificate.

https_proxy=http://127.0.0.1:8000 NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node axios.mjs

Got

Similar to node-fetch, Got doesn't support specifying the proxy using environment variables. Instead, you need to create a custom agent and pass it to the request.

Here's an example of how you can use Got with Dev Proxy:

import got from 'got';
import { HttpsProxyAgent } from 'https-proxy-agent';

(async () => {
  // Create a custom agent pointing to Dev Proxy
  const agent = new HttpsProxyAgent('http://127.0.0.1:8000');
  const result = await got('https://jsonplaceholder.typicode.com/posts', {
    // Pass the agent to the request
    agent: {
      https: agent
    }
  }).json();
  console.log(JSON.stringify(result, null, 2));
})();

When starting your app, trust the Dev Proxy root certificate:

NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node got.mjs

SuperAgent

SuperAgent doesn't support specifying the proxy using environment variables. To use Dev Proxy with SuperAgent, you need to install the superagent-proxy plugin and configure the proxy using the proxy method.

const superagent = require('superagent');
require('superagent-proxy')(superagent);

(async () => {
  const result = await superagent
    .get('https://jsonplaceholder.typicode.com/posts')
    .proxy('http://127.0.0.1:8000');
  console.log(JSON.stringify(result.body, null, 2));
})();

When starting your app, trust the Dev Proxy root certificate:

NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node superagent.js

Known issues

When you use Dev Proxy with Node.js, you might encounter the following issues.

UNABLE_TO_VERIFY_LEAF_SIGNATURE error

When you use Dev Proxy with Node.js, you get an error similar to:

/Users/user/my-app/node_modules/node-fetch/lib/index.js:1501
                        reject(new FetchError(`request to ${request.url} failed, reason: ${err.message}`, 'system', err));
                               ^
FetchError: request to https://jsonplaceholder.typicode.com/posts failed, reason: unable to verify the first certificate
    at ClientRequest.<anonymous> (/Users/user/my-app/node_modules/node-fetch/lib/index.js:1501:11)
    at ClientRequest.emit (node:events:518:28)
    at TLSSocket.socketErrorListener (node:_http_client:495:9)
    at TLSSocket.emit (node:events:518:28)
    at emitErrorNT (node:internal/streams/destroy:169:8)
    at emitErrorCloseNT (node:internal/streams/destroy:128:3)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21) {
  type: 'system',
  errno: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
  code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'
}

This error means that Node.js doesn't trust the Dev Proxy root certificate. To fix this issue, download the Dev Proxy root certificate and set the NODE_EXTRA_CA_CERTS environment variable to the path of the downloaded file when starting your app. For more information, see Trust the Dev Proxy certificate.

NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js

See also

• Use Dev Proxy with Node.js applications in Docker containers - Docker setup
• Use Dev Proxy with JavaScript Azure Functions - Azure Functions
• Glossary - Dev Proxy terminology