{"id":18278,"library":"dns-over-http","title":"dns-over-http","description":"DNS over HTTPS (DoH) client and middleware for Node.js. Version 0.2.0 provides both a server middleware for `http.createServer()` and a client for querying DNS via HTTPS. It uses centralized DNS servers (e.g., Quad9, Google, Cloudflare) and caches answers. This is an early-stage work-in-progress with limited features and no active maintenance. It differs from mature DoH libraries by offering a simple middleware interface and low-level wire format (dns-packet) support.","status":"active","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/jwerle/dns-over-http","tags":["javascript","dns","over","http","https","doh","server"],"install":[{"cmd":"npm install dns-over-http","lang":"bash","label":"npm"},{"cmd":"yarn add dns-over-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add dns-over-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for encoding and decoding DNS wire format packets.","package":"dns-packet"}],"imports":[{"note":"CJS module; ESM import may not work without bundler or esm package.","wrong":"import doh from 'dns-over-http'","symbol":"doh","correct":"const doh = require('dns-over-http')"},{"note":"If using ESM, dynamic import with .default may be required.","wrong":null,"symbol":"doh","correct":"const { default: doh } = await import('dns-over-http')"},{"note":"First argument is an options object (including url), not a path string.","wrong":"doh.query('/dns-query', questions, callback)","symbol":"doh.query","correct":"const doh = require('dns-over-http'); doh.query({url}, questions, callback)"},{"note":"doh() returns a request handler directly; no createServer method.","wrong":"const handler = doh.createServer({ servers: ['1.1.1.1'] })","symbol":"doh(opts)","correct":"const handler = doh({ servers: ['1.1.1.1'] })"}],"quickstart":{"code":"const https = require('https');\nconst doh = require('dns-over-http');\n\nconst server = https.createServer({\n  cert: process.env.SSL_CERT || '',\n  key: process.env.SSL_KEY || ''\n}, doh({\n  servers: ['9.9.9.9', '8.8.8.8', '1.1.1.1'],\n  maxAge: 600000\n}));\n\nserver.listen(3000, () => {\n  console.log('DoH server listening on port 3000');\n});\n\n// Client example\nconst results = [];\nconst lookups = [\n  { type: 'A', name: 'google.com' },\n  { type: 'AAAA', name: 'google.com' }\n];\n\nfor (const lookup of lookups) {\n  doh.query({\n    url: 'https://dns.google.com:443/experimental'\n  }, [lookup], (err, res) => {\n    if (err) throw err;\n    results.push(res.answers);\n    if (results.length === lookups.length) {\n      console.log(JSON.stringify(results, null, 2));\n    }\n  });\n}","lang":"javascript","description":"Creates a DoH server with HTTPS and performs two DNS queries via client."},"warnings":[{"fix":"Use URL like 'https://dns.google.com:443/experimental' or check provider's endpoint.","message":"Client query URL must be full HTTPS URL; path '/experimental' is specific to Google DNS.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use https.createServer with valid cert and key, or terminate SSL upstream.","message":"Server middleware does not validate HTTPS; you must wrap with https.createServer or use reverse proxy.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use doh() directly with http.createServer or adapt for Express via (req, res) signature.","message":"doh() returns a single request handler; cannot be used as Express middleware directly (expects (req, res)).","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Consider mature alternatives like node-doh or dns-over-https.","message":"Package is early WIP (version 0.2.0) with no recent updates. Not recommended for production use.","severity":"deprecated","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use const doh = require('dns-over-http') or const { default: doh } = await import('dns-over-http').","cause":"ESM import of CJS module without default handling.","error":"TypeError: doh is not a function"},{"fix":"Provide valid IP addresses like '8.8.8.8' in servers array.","cause":"Missing or invalid DNS server address in options.servers.","error":"Error: getaddrinfo ENOTFOUND"},{"fix":"Check err first; if no error, ensure res has answers property: if (res && res.answers).","cause":"Response callback may receive null or undefined for failed queries.","error":"TypeError: Cannot read properties of undefined (reading 'answers')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}