{"id":16860,"library":"negotiator","title":"HTTP Content Negotiation","description":"Negotiator is a lightweight, standalone utility for parsing and evaluating HTTP `Accept`, `Accept-Language`, `Accept-Encoding`, and `Accept-Charset` headers. It allows servers to determine the client's preferred content based on quality values (`q-factors`) specified in these headers. Primarily maintained by the `jshttp` organization, it serves as a core component for web frameworks like Express.js by abstracting complex RFC specifications for content negotiation. The current stable version is `1.0.0`. The package operates in a maintenance mode, with infrequent but significant major releases that often include breaking changes to align with evolving Node.js environments and best practices. It distinguishes itself by providing a robust and dependency-free solution for this specific HTTP concern.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/jshttp/negotiator","tags":["javascript","http","content negotiation","accept","accept-language","accept-encoding","accept-charset"],"install":[{"cmd":"npm install negotiator","lang":"bash","label":"npm"},{"cmd":"yarn add negotiator","lang":"bash","label":"yarn"},{"cmd":"pnpm add negotiator","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary export is a default export representing the Negotiator constructor. Avoid named imports for the main class.","wrong":"import { Negotiator } from 'negotiator'","symbol":"Negotiator","correct":"import Negotiator from 'negotiator'"},{"note":"For CommonJS, the module exports the Negotiator constructor directly.","wrong":"const { Negotiator } = require('negotiator')","symbol":"Negotiator","correct":"const Negotiator = require('negotiator')"}],"quickstart":{"code":"import Negotiator from 'negotiator';\n\nconst mockRequest = {\n  headers: {\n    'accept': 'text/html, application/xhtml+xml, application/json;q=0.9, image/webp, */*;q=0.8',\n    'accept-language': 'en-US,en;q=0.9,es;q=0.7',\n    'accept-encoding': 'gzip, deflate, br;q=0.9, identity;q=0.5'\n  }\n};\n\nconst negotiator = new Negotiator(mockRequest);\n\nconsole.log('Preferred Media Types (all):', negotiator.mediaTypes());\nconsole.log('Preferred Media Type (available):', negotiator.mediaType(['application/json', 'text/plain']));\n\nconsole.log('Preferred Languages (all):', negotiator.languages());\nconsole.log('Preferred Language (available):', negotiator.language(['es', 'fr']));\n\nconsole.log('Preferred Encodings (all):', negotiator.encodings());\nconsole.log('Preferred Encoding (available):', negotiator.encoding(['gzip', 'br', 'identity']));\n\n/* Example Output:\nPreferred Media Types (all): [ 'text/html', 'application/xhtml+xml', 'application/json', 'image/webp', '*/*' ]\nPreferred Media Type (available): application/json\nPreferred Languages (all): [ 'en-US', 'en', 'es' ]\nPreferred Language (available): es\nPreferred Encodings (all): [ 'gzip', 'br', 'identity', 'deflate' ]\nPreferred Encoding (available): gzip\n*/","lang":"javascript","description":"Demonstrates initializing Negotiator with mock request headers and using its methods to determine preferred content types, languages, and encodings based on client preferences and available options."},"warnings":[{"fix":"Upgrade Node.js to version 18 or higher, or pin `negotiator` to `^0.6.0` in your `package.json`.","message":"Version `1.0.0` dropped support for Node.js versions older than 18. Applications running on Node.js <18 must remain on `negotiator@0.6.x` or upgrade their Node.js environment.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Thoroughly test negotiation logic with various `Accept` header values and explicit `q` factors. Refer to RFC 7231 for details on `q` values.","message":"Incorrect understanding or parsing of `q` values (quality factors) in `Accept` headers can lead to unexpected negotiation results. The `negotiator` library correctly sorts preferences, but developers must ensure their available lists align with expected client preferences.","severity":"gotcha","affected_versions":">=0.5.0"},{"fix":"Upgrade to `negotiator@0.5.3` or newer to benefit from internal fixes for case-insensitive parameter matching. Always test your header parsing logic.","message":"Media type parameters and header values are typically case-insensitive according to HTTP specifications. Older versions (pre-0.5.3) had fixes related to case-insensitivity in matching. Ensure your application's `available` lists use consistent casing or handle potential variations if manually constructing them.","severity":"gotcha","affected_versions":"<0.5.3"},{"fix":"Always include `identity` in your `availableEncodings` list if you intend to support uncompressed responses, and be aware of its default `q` value if not specified otherwise.","message":"When dealing with `Accept-Encoding`, the `identity` encoding is implicitly supported unless explicitly excluded by a `q=0` factor. The library handles this, but applications might overlook `identity` when checking for available encodings, leading to unexpected default behavior.","severity":"gotcha","affected_versions":">=0.5.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For ESM, use `import Negotiator from 'negotiator';`. For CommonJS, use `const Negotiator = require('negotiator');` and then `new Negotiator(request);`.","cause":"Attempting to instantiate `Negotiator` when it was imported incorrectly, often due to a named import or incorrect CommonJS `require` usage.","error":"TypeError: Negotiator is not a constructor"},{"fix":"Inspect the raw `Accept` headers received by the server. Verify the `q` values and syntax. Ensure the `available` array passed to `negotiator.mediaType(available)` accurately reflects what your application can provide and is not empty.","cause":"The `Accept` header or corresponding `Accept-` header from the client either has unexpected `q` values, a different order of preference, or the `available` list provided to the negotiator method does not match the expected options.","error":"Unexpected content type/language/encoding returned by negotiator.mediaType() (or similar method)"}],"ecosystem":"npm","meta_description":null}