DNS Prefetch Control Middleware for Express

Common errors

• TypeError: dnsPrefetchControl is not a function

  cause This usually occurs when attempting to use an ESM `import` statement for a CommonJS module that exports a function directly (e.g., `module.exports = function`) without correctly accessing its default property, or if using a named import for a default export.
  fix Ensure correct import syntax: `import dnsPrefetchControl from 'dns-prefetch-control';` for ESM, or `const dnsPrefetchControl = require('dns-prefetch-control');` for CommonJS. If using TypeScript and `esModuleInterop` is `false`, you might need `import * as dnsPrefetchControl from 'dns-prefetch-control';`.

• X-DNS-Prefetch-Control header is not being set or has an unexpected value

  cause The middleware might not be applied correctly to the Express application, or other middleware might be overwriting the header. Also, if using the standalone package alongside `helmet`, `helmet` might take precedence.
  fix Verify `app.use(dnsPrefetchControl(...))` is placed early in your middleware chain. If using `helmet`, ensure `xDnsPrefetchControl` is configured within the `helmet` options object and avoid redundant standalone `dns-prefetch-control` usage. Use browser developer tools to inspect response headers.

Warnings

• deprecated The standalone `dns-prefetch-control` package is effectively abandoned, with its GitHub repository archived. Its functionality has been integrated directly into the `helmet` package. Users should migrate to using `helmet` directly for this feature.
  Fix: Migrate to `helmet` and configure `xDnsPrefetchControl` option: `app.use(helmet({ xDnsPrefetchControl: { allow: false } }));`
• gotcha Enabling DNS prefetching (`allow: true`) can improve page load performance by proactively resolving domain names. However, it can also have privacy implications, as it causes browsers to make DNS requests for links a user might not actually click, potentially revealing browsing interests to DNS servers and network observers.
  Fix: The default setting of `allow: false` (or just `app.use(dnsPrefetchControl())`) disables prefetching, prioritizing privacy. Carefully evaluate performance gains against privacy concerns before enabling.
• gotcha The `X-DNS-Prefetch-Control` header is a non-standard header, though widely supported by modern browsers. Its behavior might vary slightly across different browser implementations.
  Fix: Be aware that reliance on non-standard headers can lead to inconsistent behavior in edge cases or with future browser updates. Monitor browser compatibility if this header is critical to your application's privacy or performance strategy.
• gotcha Overusing DNS prefetch hints (e.g., via `<link rel="dns-prefetch" ...>` or excessively broad prefetching) can paradoxically degrade performance by overwhelming the browser's internal queue or causing unnecessary lookups, especially for domains that are not actually used.
  Fix: Focus DNS prefetching only on key third-party domains used early in the page load and avoid prefetching low-priority or rarely used domains. The middleware controls the HTTP header, which typically applies broadly, so fine-tuning often requires manual `<link>` tags for specific domains if `allow: true` is used.

Install

• npm install dns-prefetch-control npm
• yarn add dns-prefetch-control yarn
• pnpm add dns-prefetch-control pnpm

Imports

• dnsPrefetchControl
  wrong:

  const dnsPrefetchControl = require('dns-prefetch-control'); // Correct for CJS, but prefer ESM where possible.
  // import { dnsPrefetchControl } from 'dns-prefetch-control'; // Incorrect named import for CJS default export.

  correct:

  import dnsPrefetchControl from 'dns-prefetch-control';

  For ESM, this imports the default CommonJS export. This standalone package is largely superseded; use the `helmet` package instead for modern applications.
• DnsPrefetchControlOptions

  import { DnsPrefetchControlOptions } from 'dns-prefetch-control';

  Imports the TypeScript type for configuration options. The package ships with built-in type declarations. This package is largely superseded; use the `helmet` package instead.
• dnsPrefetchControl (from Helmet)
  wrong:

  import { dnsPrefetchControl } from 'helmet';

  correct:

  import helmet from 'helmet';
  // ... app.use(helmet({ xDnsPrefetchControl: { allow: true } }));

  This is the recommended modern way to apply DNS prefetch control. The functionality is exposed as an option within the main `helmet` middleware, not as a direct named export from `helmet` itself. The standalone package is abandoned.

Quickstart

Demonstrates setting the X-DNS-Prefetch-Control header using the middleware, defaulting to 'off', and notes the modern Helmet.js integration.

import express from 'express';
import dnsPrefetchControl from 'dns-prefetch-control';
// For modern usage, consider importing helmet directly:
// import helmet from 'helmet';

const app = express();
const PORT = process.env.PORT || 3000;

// Use dns-prefetch-control to disable DNS prefetching (default and recommended for privacy)
app.use(dnsPrefetchControl());

// Example of explicitly allowing DNS prefetching (potential privacy trade-off, slight performance gain)
// app.use(dnsPrefetchControl({ allow: true }));

// If using Helmet.js, you would configure it like this (and omit the standalone middleware):
// app.use(helmet({
//   xDnsPrefetchControl: { allow: false } // or true
// }));

app.get('/', (req, res) => {
  res.send('<h1>DNS Prefetch Control Example</h1><p>Check your network headers for X-DNS-Prefetch-Control.</p>');
});

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log('X-DNS-Prefetch-Control header should be set.');
});