HTTP Vary Header Manipulator

1.1.2 · active · verified Tue Apr 21

`vary` is a focused Node.js utility library designed for manipulating the HTTP `Vary` response header. It provides a simple API to append fields to the `Vary` header of a Node.js `http.ServerResponse` object or directly to an existing `Vary` header string. Currently at version 1.1.2, the package maintains a stable and slow release cadence, primarily focusing on performance improvements and input validation rather than frequent feature additions. Its key differentiator is its singular purpose, offering a reliable and minimal solution for ensuring correct cache behavior when content varies based on request headers, without introducing additional HTTP framework overhead. It is a foundational utility used by many HTTP servers and middleware in the Node.js ecosystem.

Common errors

```
TypeError: vary is not a function
```
cause Attempting to use `import vary from 'vary'` in an ES Module context or when `esModuleInterop` is not enabled in TypeScript.

fix Change the import statement to `const vary = require('vary')`.
```
Error: Invalid field name
```
cause Passing a non-string, empty string, or syntactically invalid HTTP field name to `vary(res, field)` or `vary.append(header, field)`.

fix Ensure the `field` argument is a non-empty string representing a valid HTTP header field name (e.g., 'User-Agent', 'Accept-Encoding'). Refer to RFC 7231 for valid field name syntax.

Warnings

breaking Starting with v1.1.0, the `vary` function strictly enforces valid HTTP field names. If you pass an invalid or malformed field name, it will now be rejected, whereas previous versions might have silently ignored or attempted to normalize it, potentially leading to a valid but unintended header value.
Fix: Ensure all `field` arguments passed to `vary(res, field)` or `vary.append(header, field)` conform to valid HTTP header field name syntax.
gotcha The `vary` package is a CommonJS module and does not natively support ES Modules (`import`/`export`) syntax. Attempting to import it using `import vary from 'vary'` will likely result in a runtime error.
Fix: Always use `const vary = require('vary')` to import the module in both JavaScript and TypeScript projects (or configure TypeScript's `esModuleInterop` and `allowSyntheticDefaultImports` if you prefer `import` syntax).
gotcha While `vary` can accept a string of multiple fields (e.g., `'Accept, User-Agent'`) or an array of fields, it's crucial to understand that it appends and deduplicates. If you provide a field already present, it maintains its position rather than moving it to the end.
Fix: Understand `vary`'s behavior: it's designed to ensure a field is *present* in the `Vary` header without duplicating it or altering its existing order if already present. For complete control over header order, manipulate the string directly or use `vary.append` with an initial empty string.

Install

npm install vary npm
yarn add vary yarn
pnpm add vary pnpm

Imports

vary
wrong:
```
import vary from 'vary'
```
correct:
```
const vary = require('vary')
```
This package is CommonJS-only. Direct ESM imports like `import vary from 'vary'` or `import { vary } from 'vary'` are not supported and will result in runtime errors. TypeScript users should use `import vary = require('vary');` or enable `esModuleInterop`.
vary.append
wrong:
```
import { append } from 'vary'
```
correct:
```
const vary = require('vary'); vary.append(header, field)
```
`append` is a named export on the main `vary` object, not a separate top-level export. You must import the `vary` object first.

Quickstart

Demonstrates how to use `vary(res, field)` to add a field to the Vary header of an HTTP response and `vary.append(header, field)` to manipulate a header string.

const http = require('http');
const vary = require('vary');

http.createServer(function onRequest (req, res) {
  // About to user-agent sniff, so add User-Agent to Vary header
  vary(res, 'User-Agent');

  const ua = req.headers['user-agent'] || '';
  const isMobile = /mobi|android|touch|mini/i.test(ua);

  // Serve site, depending on isMobile
  res.setHeader('Content-Type', 'text/html');
  res.end('You are (probably) ' + (isMobile ? '' : 'not ') + 'a mobile user');
}).listen(3000, () => {
  console.log('Server listening on http://localhost:3000');
});

// Example of using vary.append directly on a string
const initialVaryHeader = 'Accept, Accept-Encoding';
const newVaryHeader = vary.append(initialVaryHeader, 'Origin');
console.log('Appended Vary header:', newVaryHeader); // 'Accept, Accept-Encoding, Origin'

view raw JSON →