DNS over HTTP Resolver

Common errors

• TypeError: DnsOverHttpResolver is not a constructor

  cause Attempting to instantiate `DnsOverHttpResolver` using CommonJS `require()` syntax in an ES module environment or with a package that has `"type": "module"`.
  fix Change your import statement to `import { DnsOverHttpResolver } from 'dns-over-http-resolver';` and ensure your environment supports ES modules.

• ReferenceError: fetch is not defined

  cause The `fetch` API, used by `dns-over-http-resolver`, is not available in the current JavaScript runtime. This commonly occurs in Node.js versions older than 18.
  fix Upgrade to Node.js v18 or newer, or install a `fetch` polyfill (e.g., `node-fetch`) and ensure it's loaded globally before `dns-over-http-resolver` is used (e.g., `globalThis.fetch = require('node-fetch');`).

• ERR_MODULE_NOT_FOUND: Cannot find package 'dns-over-http-resolver' imported from ...

  cause The module loader cannot locate the package due to an incorrect import path, missing installation, or misconfigured module resolution.
  fix Verify the package is installed (`npm install dns-over-http-resolver`), and ensure your import path is correct: `import { DnsOverHttpResolver } from 'dns-over-http-resolver';`.

Warnings

• breaking Beginning with version 3.0.0, the package transitioned to being an ES Module (ESM) exclusively. This change breaks direct `require()` calls for the main `DnsOverHttpResolver` class.
  Fix: Update your import statements to use ES module syntax: `import { DnsOverHttpResolver } from 'dns-over-http-resolver'`. Ensure your project is configured for ESM.
• gotcha The library relies on the global `fetch` API. In Node.js environments prior to version 18, `fetch` is not native and must be polyfilled or provided by an external library (e.g., `node-fetch`) for `dns-over-http-resolver` to function correctly.
  Fix: Ensure `fetch` is available in your runtime. For Node.js <18, install and import a `fetch` polyfill (e.g., `import 'node-fetch'`) at the application's entry point, or upgrade to Node.js 18 or newer.
• gotcha When `dns-over-http-resolver` is included directly via a `<script>` tag in a browser, its exports are available under a global `DnsOverHttpResolver` object. To instantiate the resolver class, you must access it as `new DnsOverHttpResolver.DnsOverHttpResolver()`.
  Fix: If using a script tag for browser loading, instantiate the class using `new DnsOverHttpResolver.DnsOverHttpResolver()`. For module-based browser builds, use standard `import` statements.

Install

• npm install dns-over-http-resolver npm
• yarn add dns-over-http-resolver yarn
• pnpm add dns-over-http-resolver pnpm

Imports

• DnsOverHttpResolver
  wrong:

  const DnsOverHttpResolver = require('dns-over-http-resolver')

  correct:

  import { DnsOverHttpResolver } from 'dns-over-http-resolver'

  The package transitioned to ES Module (ESM) only from v3 onwards. CommonJS `require` is no longer supported for direct import of the main class.
• Resolver methods (e.g., resolve4)
  wrong:

  import { resolve4 } from 'dns-over-http-resolver'

  correct:

  const resolver = new DnsOverHttpResolver(); await resolver.resolve4('example.com')

  Resolution methods like `resolve4`, `resolveTxt`, `setServers` are instance methods of `DnsOverHttpResolver`, not named exports directly from the module root.
• DnsOverHttpResolver (browser global)
  wrong:

  const resolver = new DnsOverHttpResolver(); // Direct access without namespace

  correct:

  <script src="https://unpkg.com/dns-over-http-resolver/dist/index.min.js"></script>
  // Then access via: const resolver = new DnsOverHttpResolver.DnsOverHttpResolver();

  When loaded via a script tag, the module's exports are made available under a global object named `DnsOverHttpResolver`. The class itself is accessible as `DnsOverHttpResolver.DnsOverHttpResolver`.

Quickstart

This example demonstrates how to import and instantiate the `DnsOverHttpResolver`, perform various DNS record lookups (A, TXT, MX), configure built-in caching, and dynamically update the list of DNS over HTTP servers for customized resolution.

import { DnsOverHttpResolver } from 'dns-over-http-resolver';

async function resolveDnsRecords() {
  const resolver = new DnsOverHttpResolver({
    maxCache: 200 // Configure cache size; default is 100
  });

  try {
    // Resolve A records (IPv4 addresses)
    console.log('Resolving A records for example.com...');
    const ipv4Addresses = await resolver.resolve4('example.com');
    console.log('IPv4 Addresses:', ipv4Addresses);

    // Resolve TXT records
    console.log('\nResolving TXT records for google.com...');
    const txtRecords = await resolver.resolveTxt('google.com');
    console.log('TXT Records:', txtRecords);

    // Resolve any record type (e.g., MX records for a mail server)
    console.log('\nResolving MX records for gmail.com...');
    const mxRecords = await resolver.resolve('gmail.com', 'MX');
    console.log('MX Records:', mxRecords);

    // Get current servers and set custom DNS over HTTP servers
    console.log('\nDefault servers:', resolver.getServers());
    resolver.setServers([
      'https://dns.quad9.net/dns-query', // Example: Quad9
      'https://dns.opendns.com/dns-query' // Example: OpenDNS
    ]);
    console.log('Updated servers:', resolver.getServers());

    // Resolve another domain with the newly configured servers
    const newIpv4 = await resolver.resolve4('cloudflare.com');
    console.log('IPv4 for cloudflare.com (via custom servers):', newIpv4);

  } catch (error) {
    console.error('DNS resolution failed:', error);
  }
}

resolveDnsRecords().catch(err => {
  console.error('An unhandled error occurred during quickstart execution:', err);
});