Blazing-fast Node.js `dns` for React Native. Built with Nitro (JSI) & Rust, supporting DoH/DoT/DoQ and global native network interception.
react-native-nitro-dns is a high-performance DNS module for React Native, powered by Nitro Modules and a robust Rust core. It provides a Node.js-compatible dns API while extending modern privacy protocols (DoH, DoT, DoQ) and global network interception for mobile apps.

![platform]()
![compatibility]()
δΈζζζ‘£
---
- π Extreme Performance: Core logic implemented in Rust with zero-copy JSI/C++ calls via Nitro Modules, bypassing the bridge.
- π¦ Node.js Compatible: Supports lookup, resolve*, reverse, lookupService, and dns.promises APIs.
- π‘οΈ Modern Privacy:
- DoH (DNS over HTTPS) - Custom paths supported.
- DoT (DNS over TLS).
- DoQ (DNS over QUIC).
- π Global Interception: Intercept all native network requests (fetch, XMLHttpRequest, etc.) and apply custom resolution rules.
- π Cross-Platform Consistency: Unified logic for Android (OkHttp Hook) and iOS (NSURLProtocol).
- π§© Advanced Config: SNI override (Bootstrap IP), timeout management, retry logic, and IPv4/IPv6 prioritization.
- β‘ Enhanced Caching: High-performance native cache with Stale-While-Revalidate (SWR) and Stale-If-Error (SIE) support.
---
``bashUsing npm
npm install react-native-nitro-dns
$3
iOS implementation is based on
NSURLProtocol. It is automatically linked by Nitro, usually requiring no manual AppDelegate changes.$3
To enable global OkHttp interception on Android, inject the Nitro factory in your
MainApplication.kt (or MainApplication.java):`kotlin
// MainApplication.kt (React Native 0.73+)
import com.nitrodns.NitroOkHttpClientFactory
import com.facebook.react.modules.network.OkHttpClientProvideroverride fun onCreate() {
super.onCreate()
// Inject Nitro DNS factory for global fetch/XHR interception
OkHttpClientProvider.setOkHttpClientFactory(NitroOkHttpClientFactory())
}
`---
π Quick Start
$3
`typescript
import dns from 'react-native-nitro-dns';// Using Promise APIs
const { address, family } = await dns.promises.lookup('google.com');
// Get all IP addresses via resolve4
const addresses = await dns.promises.resolve4('example.com');
`$3
`typescript
// Configure DoH with custom path
dns.setServers(['https://dns.alidns.com/dns-query']);// Configure DoT
dns.setServers(['tls://dns.google']);
// Hybrid configuration (Load balancing or failover)
dns.setServers(['quic://dns.nextdns.io', '8.8.8.8']);
`$3
Once enabled, all network requests (e.g.,
fetch('https://...')) will use Nitro DNS for resolution instead of system cache.`typescript
// Enable interception
dns.setNativeInterceptionEnabled(true);// This fetch call is now controlled by Nitro DNS (supporting DoH/DoT/etc.)
const res = await fetch('https://my-secure-api.com');
`$3
Optimize resolution speed and reliability with advanced caching policies.
`typescript
import dns, { CachePolicy } from 'react-native-nitro-dns';// Set global cache size
dns.setCacheSize(1000);
// Set global cache policy to Stale-While-Revalidate (SWR)
// Serves stale data immediately while refreshing in background
dns.setCachePolicy(CachePolicy.StaleWhileRevalidate, 86400); // 1 day grace
`---
π API Reference
$3
| Method | Description | Return Value | Advanced |
| :--- | :--- | :--- | :--- |
|
lookup | Resolves a hostname | {address, family} | Supports all, verbatim, family via options |
| resolve4 | Resolves IPv4 addresses | string[] | Set {ttl: true} for [{address, ttl}] |
| resolve6 | Resolves IPv6 addresses | string[] | Set {ttl: true} for [{address, ttl}] |
| resolveMx | Resolves Mail Exchange records | {exchange, priority}[] | - |
| resolveTxt | Resolves Text records | string[][] | - |
| resolveTlsa | Resolves DANE fingerprints | TLSA[] | - |
| lookupService | Reverse lookup for IP/Port | {hostname, service} | - |
| clearCache | Clears all DNS caches | void | - |
| setCacheSize | Sets global cache size | void | Default is 32 |
| setCachePolicy| Sets global cache strategy | void | Supports SWR/SIE policies |$3
Standard Node.js constants for
lookup hints:
- ADDRCONFIG
- V4MAPPED
- ALL---
$3
Route specific domains to specific servers while using defaults for others.
Format:
/domain/server_url`typescript
dns.setServers([
'/google.com/8.8.8.8', // Use 8.8.8.8 for google.com and its subdomains
'/corp.local/10.0.0.1', // Use internal DNS for local corp domains
'1.1.1.1' // Default server for everyone else
]);
`$3
Use the
system keyword to refer to the device's original DNS configuration. This is useful for VPN/Intranet routing.`typescript
dns.setServers([
'/my-company.com/system', // Use system resolver for company intranet
'https://dns.google/dns-query' // Use Google DoH for everything else
]);
`---
π οΈ Advanced Usage
$3
If you need isolated DNS configurations (e.g., for different environments):
`typescript
const customResolver = new dns.Resolver({
timeout: 3000, // ms
tries: 2, // retry attempts
cacheSize: 500 // instance-specific cache capacity
});
customResolver.setServers(['1.1.1.1']);
const ips = await customResolver.promises.resolve4('github.com');
`$3
To prevent DNS hijacking of the DoH/DoT server itself, specify a hardcoded IP and SNI:
Format:
protocol://IP/path#OriginalHostname`typescript
// Force connect to 8.8.8.8 for DoH, using dns.google for SNI validation
dns.setServers(['https://8.8.8.8/dns-query#dns.google']);// Force connect to 223.5.5.5 for DoT, using dns.alidns.com for SNI
dns.setServers(['tls://223.5.5.5#dns.alidns.com']);
`$3
The
CachePolicy enum defines how the internal and background caches behave:| Policy | Description |
| :--- | :--- |
|
FollowDnsTtl (0) | Default. Strictly follows the TTL returned by DNS servers. |
| Bypass (1) | Disables all caching; every request hits the network. |
| StaleWhileRevalidate (2) | Returns stale data immediately if available while fetching fresh data in the background (refreshed on subsequent calls). |
| StaleIfError (3) | Returns stale data if the DNS server is unreachable or returns an error. |---
π Architecture
`mermaid
graph LR
JS[JavaScript App] -- JSI --> Nitro[Nitro Modules C++]
Nitro -- FFI --> Rust[Rust Core]
Rust -- System --> OS[iOS/Android Network Stack]
`$3
- iOS (NSURLProtocol): Intercepts all NSURLSession tasks. Handles HTTPS SNI validation by extracting certificates and verifying against the original hostname even when connecting via raw IP. Includes smart 3xx redirect handling.
- Android (OkHttp Hook): Injects a custom Dns proxy into the OkHttpClient`. This provides non-invasive support for most networking libraries (including React Native's core Networking).---
ISC