{"id":16006,"library":"dns-over-http-resolver","title":"DNS over HTTP Resolver","description":"This package provides an isomorphic (browser and Node.js) DNS over HTTP (DoH) resolver, leveraging the `fetch` API for network requests. It offers an API interface designed to be compatible with Node.js's built-in `dns.promises` API, simplifying migration or usage in environments where a native DNS resolver is desired but not available or insufficient. The current stable version is 3.0.16, with releases occurring roughly monthly or bi-monthly, primarily for dependency updates and minor improvements. Key differentiators include its `fetch`-based approach, built-in caching (configurable `maxCache`), and the ability to specify custom DoH servers, making it flexible for various privacy and performance requirements beyond the default Cloudflare and Google servers. It ships with TypeScript types, enhancing developer experience and type safety.","status":"active","version":"3.0.16","language":"javascript","source_language":"en","source_url":"https://github.com/vasco-santos/dns-over-http-resolver","tags":["javascript","dns","doh","http","typescript"],"install":[{"cmd":"npm install dns-over-http-resolver","lang":"bash","label":"npm"},{"cmd":"yarn add dns-over-http-resolver","lang":"bash","label":"yarn"},{"cmd":"pnpm add dns-over-http-resolver","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package transitioned to ES Module (ESM) only from v3 onwards. CommonJS `require` is no longer supported for direct import of the main class.","wrong":"const DnsOverHttpResolver = require('dns-over-http-resolver')","symbol":"DnsOverHttpResolver","correct":"import { DnsOverHttpResolver } from 'dns-over-http-resolver'"},{"note":"Resolution methods like `resolve4`, `resolveTxt`, `setServers` are instance methods of `DnsOverHttpResolver`, not named exports directly from the module root.","wrong":"import { resolve4 } from 'dns-over-http-resolver'","symbol":"Resolver methods (e.g., resolve4)","correct":"const resolver = new DnsOverHttpResolver(); await resolver.resolve4('example.com')"},{"note":"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`.","wrong":"const resolver = new DnsOverHttpResolver(); // Direct access without namespace","symbol":"DnsOverHttpResolver (browser global)","correct":"<script src=\"https://unpkg.com/dns-over-http-resolver/dist/index.min.js\"></script>\n// Then access via: const resolver = new DnsOverHttpResolver.DnsOverHttpResolver();"}],"quickstart":{"code":"import { DnsOverHttpResolver } from 'dns-over-http-resolver';\n\nasync function resolveDnsRecords() {\n  const resolver = new DnsOverHttpResolver({\n    maxCache: 200 // Configure cache size; default is 100\n  });\n\n  try {\n    // Resolve A records (IPv4 addresses)\n    console.log('Resolving A records for example.com...');\n    const ipv4Addresses = await resolver.resolve4('example.com');\n    console.log('IPv4 Addresses:', ipv4Addresses);\n\n    // Resolve TXT records\n    console.log('\\nResolving TXT records for google.com...');\n    const txtRecords = await resolver.resolveTxt('google.com');\n    console.log('TXT Records:', txtRecords);\n\n    // Resolve any record type (e.g., MX records for a mail server)\n    console.log('\\nResolving MX records for gmail.com...');\n    const mxRecords = await resolver.resolve('gmail.com', 'MX');\n    console.log('MX Records:', mxRecords);\n\n    // Get current servers and set custom DNS over HTTP servers\n    console.log('\\nDefault servers:', resolver.getServers());\n    resolver.setServers([\n      'https://dns.quad9.net/dns-query', // Example: Quad9\n      'https://dns.opendns.com/dns-query' // Example: OpenDNS\n    ]);\n    console.log('Updated servers:', resolver.getServers());\n\n    // Resolve another domain with the newly configured servers\n    const newIpv4 = await resolver.resolve4('cloudflare.com');\n    console.log('IPv4 for cloudflare.com (via custom servers):', newIpv4);\n\n  } catch (error) {\n    console.error('DNS resolution failed:', error);\n  }\n}\n\nresolveDnsRecords().catch(err => {\n  console.error('An unhandled error occurred during quickstart execution:', err);\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Update your import statements to use ES module syntax: `import { DnsOverHttpResolver } from 'dns-over-http-resolver'`. Ensure your project is configured for ESM.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<18.0.0 (Node.js)"},{"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.","message":"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()`.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import { DnsOverHttpResolver } from 'dns-over-http-resolver';` and ensure your environment supports ES modules.","cause":"Attempting to instantiate `DnsOverHttpResolver` using CommonJS `require()` syntax in an ES module environment or with a package that has `\"type\": \"module\"`.","error":"TypeError: DnsOverHttpResolver is not a constructor"},{"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');`).","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.","error":"ReferenceError: fetch is not defined"},{"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';`.","cause":"The module loader cannot locate the package due to an incorrect import path, missing installation, or misconfigured module resolution.","error":"ERR_MODULE_NOT_FOUND: Cannot find package 'dns-over-http-resolver' imported from ..."}],"ecosystem":"npm"}