Registry / web-framework / express-negotiator

express-negotiator

library1.1.0jsnpmunverified

An Express/Connect middleware for content negotiation of static files, inspired by Apache mod_negotiation. Version 1.1.0 has no recent updates. It rewrites req.url based on exact matches, locale GET parameter, cookie, and Accept-Language/Accept headers, in priority order. Differentiates from other negotiation libraries by integrating directly with express.static and handling ETags for conditional requests. Requires cookieParser when using cookie-based locale.

web-framework http-networking

npm install express-negotiator

package ↗

INSTALL

IMPORT

SIG · EXPRESS-NEGOTIATOR

express-negotiator

web-frameworkjavascriptv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import negotiator from 'express-negotiator'

✗ const negotiator = require('express-negotiator')

ESM default import; CJS require is also supported for compatibility.

negotiator

✓ import negotiator from 'express-negotiator'

✗ import { negotiator } from 'express-negotiator'

The module exports a single function; named import will not work.

negotiator

✓ const negotiator = require('express-negotiator')

✗ const { negotiator } = require('express-negotiator')

CommonJS require returns the function directly; destructuring will get undefined.

Sets up express with negotiator middleware before static file serving, using a locale cookie for negotiation.

import express from 'express'; import negotiator from 'express-negotiator'; import cookieParser from 'cookie-parser'; const root = '/path/to/static/files'; const app = express(); app.use(cookieParser()); app.use(negotiator({ root: root, cookieName: 'locale' })); app.use(express.static(root)); app.listen(1337, () => { console.log('Server listening on port 1337'); });

Debug

Known issues

gotchaNegotiator rewrites req.url to a negotiated filename, which may affect downstream middleware that inspects req.url.

fix

Run negotiator right before express.static and after any middleware that depends on the original url.

affects: *

deprecatedThe package uses express.cookieParser() which is deprecated in Express 4+; use cookie-parser middleware instead.

fix

Install and use cookie-parser as a separate middleware.

affects: express >=4

gotchaWhen no acceptable file is found, req.url is left untouched, which may cause the static middleware to serve a non-negotiated file or 404.

fix

Ensure that your static root contains all negotiated variants or handle the case when no match is found.

affects: *

gotchaThe ETag format includes Content-Type and locale, but if you use a CDN or proxy that calculates its own ETag, conditional requests may not work as expected.

fix

Disable custom ETag generation in the CDN/proxy or ensure it passes the ETag from the origin.

affects: *

gotchaIf the request URL already exactly matches a file, negotiator does not rewrite, ignoring the negotiation parameters.

fix

Design your URL scheme to avoid exact matches when negotiation is desired, e.g., use a path without extension.

affects: *

Errors

Common errors & fixes

Error: Most middleware (like cookieParser) is no longer bundled with Express and must be installed separately.

Express 4+ removed bundled middleware; cookieParser is now in the cookie-parser package.

fix

Run 'npm install cookie-parser' and use 'import cookieParser from 'cookie-parser'' instead of 'express.cookieParser()'.

TypeError: negotiator is not a function

Named import instead of default import in ESM.

fix

Use 'import negotiator from 'express-negotiator'' instead of 'import { negotiator } from 'express-negotiator''.

Cannot find module 'express-negotiator'

Package not installed.

fix

Run 'npm install express-negotiator' in your project directory.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

expressoptionalPeer dependency for middleware usage

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/express-negotiator ↗