MDN’s new design is in Beta! A sneak peek: https://blog.mozilla.org/opendesign/mdns-new-design-beta/

Use the proxy API to register an extended Proxy Auto-Configuration (PAC) file, which implements a policy for proxying web requests.

Note that Google Chrome provides an extension API also called "proxy" which is functionally similar to this API, in that extensions can use it to implement a proxying policy. However, the design of the Chrome API is completely different to this API. With Chrome's API an extension can register a PAC file, but can also define explicit proxying rules. Since this is also possible using the extended PAC files, this API only supports the PAC file approach. Because this API is incompatible with the Chrome proxy API, this API is only available through the browser namespace.

To use this API you need to have the "proxy" permission.

Communicating with PAC files

You can exchange messages between the PAC file and your add-on's background page (or any other privileged pages, like popup pages) using runtime.sendMessage() and runtime.onMessage.

To send a message to the PAC file, you must set the toProxyScript option:

// background.js

// Log any messages from the proxy.
browser.runtime.onMessage.addListener((message, sender) => {
  if (sender.url ===  browser.extension.getURL(proxyScriptURL)) {
    console.log(message);
  }
});

let messageToProxy = {
  enabled: true,
  foo: "A string",
  bar: 1234
};

browser.runtime.sendMessage(messageToProxy, {toProxyScript: true});
// pac.js

browser.runtime.onMessage.addListener((message) => {
  if (message.enabled) {
    browser.runtime.sendMessage("I'm enabled!");
  }
});

PAC file environment

The PAC file implements its proxying policy by providing an implementation of FindProxyForURL(), whose syntax is documented in the PAC documentation. Note that in Firefox, you must pass an argument to the "DIRECT" return value, even though it doesn't need an argument. This is tracked by bug 1355198.

The global helper functions usually available for PAC files (isPlainHostName(), dnsDomainIs(), and so on) are not yet available. This is tracked by bug 1353510.

Code running in the PAC file does not get access to:

//  pac.js

// send the log message to the background script
browser.runtime.sendMessage(`Proxy-blocker: blocked ${url}`);
// background-script.js

function handleMessage(message, sender) {
  // only handle messages from the proxy script
  if (sender.url !=  browser.extension.getURL(proxyScriptURL)) {
    return;
  }
  console.log(message);
}

browser.runtime.onMessage.addListener(handleMessage);

Functions

proxy.registerProxyScript()
Registers the given proxy script.

Events

proxy.onProxyError
Fired when the system encounters an error running the proxy script.

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
onProxyErrorNoNo5555No
registerProxyScriptNoNo5555No

Edge incompatibilities

Promises are not supported in Edge. Use callbacks instead.

Example Add-ons

Acknowledgements

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.

Document Tags and Contributors

 Contributors to this page: wbamberg, mwein
 Last updated by: wbamberg,