Integrate DoH in Electron - HTTPDNS - Alibaba Cloud Documentation Center

This topic describes how to use DNS over HTTPS (DoH) in Electron.

1. Introduction

Electron is a cross-platform application development framework based on Chromium and Node.js. Developers can use JavaScript, HTML, and CSS to build desktop applications.

By default, Electron uses the system's local Domain Name System (DNS) to resolve domain names. Issues with local DNS, such as hijacking, inaccurate scheduling, and high resolution latency, can cause in-app network requests to fail or be directed to incorrect service nodes. You can use DoH to address these DNS resolution issues in Electron.

2. Prerequisites

Before you integrate DoH in Electron, make sure that you have configured a DoH service.

3. Integration method

The official Electron website provides a standard solution for DoH integration. After application initialization, you can integrate DoH using <a href="https://electron.js.cn/docs/latest/api/app#appconfigurehostresolveroptions" id="371a25d48alty">app.configureHostResolver</a> to configure the DoH endpoint for HTTPDNS.

const { app } = require('electron')

app.whenReady().then(() => {
  app.configureHostResolver({
    secureDnsMode: 'automatic',
    secureDnsServers: [
       // Your DoH service link
      'https://xxx.aliyunhttpdns.com/dns-query'
    ]
  })
})

Important

Network requests in an Electron application can use the Node.js network stack or the Chromium network stack. The DoH service configured through this interface takes effect only for requests that use the Chromium network stack. These requests include the following:
- Rendering process (webpage): fetch, XMLHttpRequest, and resource loading on the page.
- Main process: use of the built-in Electron net module, BrowserWindow.loadURL(), and more.
- Preload script: use of browser APIs such as fetch and XMLHttpRequest.
The Chromium kernel uses the built-in probe domain name www.gstatic.com to check DoH availability. Until the probe is complete, the availability of the DoH service is considered undetermined. To ensure that the DoH service works as expected, make sure that the www.gstatic.com domain name is added to the resolution list or that all domain names are allowed to be resolved.
When the DoH availability is undetermined, different modes selected for secureDnsMode have different behaviors:
- automatic mode: If the DoH availability is undetermined or the service is unavailable, Chromium automatically falls back to the local DNS. After the probe is successful, it automatically switches back to DoH.
- secure mode: This mode forces the use of DoH and waits for the DoH probe result. If no active DoH endpoint is available, it does not fall back to the local DNS. To prevent your application from becoming unavailable in the rare event that the DoH service is unavailable, add other DoH services, such as free public DoH services, as a backup in secure mode.

4. Demo

Result

Demo code

const { app, BrowserWindow } = require('electron');

app.whenReady().then(async () => {
  try {
    // Configure DNS over HTTPS - automatic failover is supported
    app.configureHostResolver({
      secureDnsMode: 'automatic', // Automatically fall back to the local DNS if DoH fails
      secureDnsServers: [
         // Enter your actual DoH link here
        'https://xxxx.aliyunhttpdns.com/dns-query'
      ]
    });
    console.log('✅ DoH configured successfully: Automatic failover enabled');
  } catch (error) {
    console.error('❌ DoH configuration failed:', error);
  }

  // Create a window
  const mainWindow = new BrowserWindow({
    width: 1000,
    height: 700
  });

  mainWindow.loadURL('https://www.aliyun.com');
});

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

5. Summary

By following the steps in this topic, you can integrate the DoH feature into the Electron framework. This significantly improves your application's security and your users' privacy. After you configure DoH, you can verify the integration. To do this, set the DNS server of your local device's network to an invalid address. Then, check if network requests can still be initiated. If they can, the DoH integration is successful.