react-native-nitro-dns 🚀

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]()
中文文档

---

✨ Features

- 🚀 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.

---

📥 Installation

``bash


Using npm

npm install react-native-nitro-dns

Using yarn

yarn add 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.OkHttpClientProvider

override 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).

---

📄 License

ISC