{"id":16263,"library":"vary","title":"HTTP Vary Header Manipulator","description":"`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.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/jshttp/vary","tags":["javascript","http","res","vary"],"install":[{"cmd":"npm install vary","lang":"bash","label":"npm"},{"cmd":"yarn add vary","lang":"bash","label":"yarn"},{"cmd":"pnpm add vary","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"import vary from 'vary'","symbol":"vary","correct":"const vary = require('vary')"},{"note":"`append` is a named export on the main `vary` object, not a separate top-level export. You must import the `vary` object first.","wrong":"import { append } from 'vary'","symbol":"vary.append","correct":"const vary = require('vary'); vary.append(header, field)"}],"quickstart":{"code":"const http = require('http');\nconst vary = require('vary');\n\nhttp.createServer(function onRequest (req, res) {\n  // About to user-agent sniff, so add User-Agent to Vary header\n  vary(res, 'User-Agent');\n\n  const ua = req.headers['user-agent'] || '';\n  const isMobile = /mobi|android|touch|mini/i.test(ua);\n\n  // Serve site, depending on isMobile\n  res.setHeader('Content-Type', 'text/html');\n  res.end('You are (probably) ' + (isMobile ? '' : 'not ') + 'a mobile user');\n}).listen(3000, () => {\n  console.log('Server listening on http://localhost:3000');\n});\n\n// Example of using vary.append directly on a string\nconst initialVaryHeader = 'Accept, Accept-Encoding';\nconst newVaryHeader = vary.append(initialVaryHeader, 'Origin');\nconsole.log('Appended Vary header:', newVaryHeader); // 'Accept, Accept-Encoding, Origin'","lang":"javascript","description":"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."},"warnings":[{"fix":"Ensure all `field` arguments passed to `vary(res, field)` or `vary.append(header, field)` conform to valid HTTP header field name syntax.","message":"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.","severity":"breaking","affected_versions":">=1.1.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change the import statement to `const vary = require('vary')`.","cause":"Attempting to use `import vary from 'vary'` in an ES Module context or when `esModuleInterop` is not enabled in TypeScript.","error":"TypeError: vary is not a function"},{"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.","cause":"Passing a non-string, empty string, or syntactically invalid HTTP field name to `vary(res, field)` or `vary.append(header, field)`.","error":"Error: Invalid field name"}],"ecosystem":"npm"}