Integrate DoH in Electron - - Alibaba Cloud Documentation Center

DNS over HTTPS (DoH) encrypts DNS queries, preventing hijacking and improving resolution accuracy in Electron applications.

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. DoH addresses 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, 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

An Electron application can use either the Node.js or Chromium network stack. The DoH service configured through this interface takes effect only for requests that use the Chromium network stack:
- 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.
Chromium probes the domain name www.gstatic.com to check DoH availability. Until the probe completes, DoH availability is considered undetermined. To ensure DoH works as expected, make sure that www.gstatic.com is added to the resolution list or that all domain names are allowed to be resolved.
When DoH availability is undetermined, the secureDnsMode setting determines the behavior:
- automatic mode: If DoH is undetermined or unavailable, Chromium falls back to local DNS. After the probe succeeds, it switches back to DoH.
- secure mode: Forces DoH and waits for the probe result. If no active DoH endpoint is available, it does not fall back to local DNS. To prevent your application from becoming unavailable if the DoH service is down, add other DoH services, such as free public DoH services, as a backup.

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

Integrating DoH into Electron improves your application's security and your users' privacy. To verify the integration, set the DNS server of your local device's network to an invalid address. If network requests still succeed, the DoH integration is working correctly.