Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DnsOverHttpResolver
✓ import { DnsOverHttpResolver } from 'dns-over-http-resolver'
✗ const DnsOverHttpResolver = require('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)
✓ const resolver = new DnsOverHttpResolver(); await resolver.resolve4('example.com')
✗ import { resolve4 } from 'dns-over-http-resolver'
Resolution methods like `resolve4`, `resolveTxt`, `setServers` are instance methods of `DnsOverHttpResolver`, not named exports directly from the module root.
DnsOverHttpResolver (browser global)
✓ <script src="https://unpkg.com/dns-over-http-resolver/dist/index.min.js"></script>
// Then access via: const resolver = new DnsOverHttpResolver.DnsOverHttpResolver();
✗ const resolver = new DnsOverHttpResolver(); // Direct access without namespace
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`.
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);
});
Debug
Known issues
breakingBeginning 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.fixUpdate your import statements to use ES module syntax: `import { DnsOverHttpResolver } from 'dns-over-http-resolver'`. Ensure your project is configured for ESM. affects: >=3.0.0
gotchaThe 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.fixEnsure `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.
affects: <18.0.0 (Node.js)
gotchaWhen `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()`.fixIf using a script tag for browser loading, instantiate the class using `new DnsOverHttpResolver.DnsOverHttpResolver()`. For module-based browser builds, use standard `import` statements.
affects: >=3.0.0
Errors
Common errors & fixes
TypeError: DnsOverHttpResolver is not a constructor
Attempting to instantiate `DnsOverHttpResolver` using CommonJS `require()` syntax in an ES module environment or with a package that has `"type": "module"`.
fixChange your import statement to `import { DnsOverHttpResolver } from 'dns-over-http-resolver';` and ensure your environment supports ES modules. ReferenceError: fetch is not defined
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.
fixUpgrade 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 ...
The module loader cannot locate the package due to an incorrect import path, missing installation, or misconfigured module resolution.
fixVerify the package is installed (`npm install dns-over-http-resolver`), and ensure your import path is correct: `import { DnsOverHttpResolver } from 'dns-over-http-resolver';`. Audit
Dependencies
No dependency data recorded yet.