BuildDocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
Bun

namespace

dns

namespace dns

DNS Related APIs

  • const ADDRCONFIG: number
  • const ALL: number
  • const V4MAPPED: number
  • function getCacheStats(): { cacheHitsCompleted: number; cacheHitsInflight: number; cacheMisses: number; errors: number; size: number; totalCount: number };

    Experimental API

  • function lookup(
    hostname: string,
    options?: { backend: 'system' | 'libc' | 'c-ares' | 'getaddrinfo'; family: 0 | 4 | 6 | 'IPv4' | 'IPv6' | 'any'; flags: number; port: number; socketType: 'udp' | 'tcp' }
    ): Promise<DNSLookup[]>;

    Lookup the IP address for a hostname

    Uses non-blocking APIs by default

    @param hostname

    The hostname to lookup

    @param options

    Options for the lookup

    Basic usage

    const [{ address }] = await Bun.dns.lookup('example.com');

    Filter results to IPv4

    import { dns } from 'bun';
const [{ address }] = await dns.lookup('example.com', {family: 4});
console.log(address); // "123.122.22.126"

    Filter results to IPv6

    import { dns } from 'bun';
const [{ address }] = await dns.lookup('example.com', {family: 6});
console.log(address); // "2001:db8::1"

    DNS resolver client

    Bun supports three DNS resolvers:

    • c-ares - Uses the c-ares library to perform DNS resolution. This is the default on Linux.
    • system - Uses the system's non-blocking DNS resolver API if available, falls back to getaddrinfo. This is the default on macOS and the same as getaddrinfo on Linux.
    • getaddrinfo - Uses the posix standard getaddrinfo function. Will cause performance issues under concurrent loads.

    To customize the DNS resolver, pass a backend option to dns.lookup:

    import { dns } from 'bun';
const [{ address }] = await dns.lookup('example.com', {backend: 'getaddrinfo'});
console.log(address); // "19.42.52.62"
  • function prefetch(
    hostname: string,
    port?: number
    ): void;

    Experimental API

    Prefetch a hostname.

    This will be used by fetch() and Bun.connect() to avoid DNS lookups.

    @param hostname

    The hostname to prefetch

    @param port

    The port to prefetch. Default is 443. Port helps distinguish between IPv6 vs IPv4-only connections.

    import { dns } from 'bun';
dns.prefetch('example.com');
// ... something expensive
await fetch('https://example.com');