Enhanced Headers Class - Use SuperHeaders for lazy, typed property accessors that still work anywhere native Headers are expected
Header-Specific Classes - Purpose-built APIs for Accept, Cache-Control, Content-Type, and more
Round-Trip Safety - Parse from raw values and serialize back with .toString()
Typed Operations - Work with structured values instead of manual string parsing

Installation

npm i remix

Usage

SuperHeaders extends the native Headers class and adds lazy, typed property accessors for common headers. It is also the default export from this package.

import Headers from 'remix/headers'

let headers = new Headers(request.headers)

headers.contentType = { mediaType: 'text/html', charset: 'utf-8' }
headers.cacheControl = { public: true, maxAge: 3600 }
headers.setCookie = { name: 'session', value: 'abc', httpOnly: true }

headers.contentType.charset = 'iso-8859-1'
headers.cacheControl.maxAge = 60
headers.setCookie.push({ name: 'theme', value: 'dark', path: '/' })

return new Response(html, { headers })

Because SuperHeaders is a real Headers subclass, it can be passed directly to platform APIs:

let headers = new Headers({ contentType: 'text/plain' })

headers instanceof globalThis.Headers // true
new Response('Hello', { headers }).headers.get('Content-Type') // 'text/plain'

Typed accessors parse values only when you read them:

let headers = new Headers({ 'Content-Type': 'application/json; charset=utf-8' })

headers.get('Content-Type') // no typed parse needed
headers.contentType.mediaType // parses Content-Type lazily

Use apply() to apply a SuperHeadersInit value to an existing instance with header-aware semantics:

let headers = new Headers({
  contentType: 'text/html',
  setCookie: { name: 'session', value: 'abc' },
  vary: 'Accept-Encoding',
})

headers.apply({
  contentType: 'application/json',
  setCookie: { name: 'theme', value: 'dark' },
  vary: ['Accept-Encoding', 'Accept-Language'],
})

headers.get('Content-Type') // 'application/json'
headers.get('Vary') // 'accept-encoding, accept-language'
headers.getSetCookie() // ['session=abc', 'theme=dark']

Individual Header Utilities

Each supported header has a class that represents the header value. Use the static from() method to parse header values. Each class has a toString() method that returns the header value as a string, which you can either call manually, or will be called automatically when the header class is used in a context that expects a string.

The following headers are currently supported:

If you only need a specific header parser (for example, just Content-Type), import that parser directly from its subpath. This avoids pulling the package barrel and SuperHeaders:

import { ContentType } from 'remix/headers/content-type'
import { SetCookie } from 'remix/headers/set-cookie'

let contentType = ContentType.from('text/plain; charset=utf-8')
let setCookie = new SetCookie('session=abc; Path=/')

Accept

Parse, manipulate and stringify Accept headers.

Implements Map<mediaType, quality>.

import { Accept } from 'remix/headers'

// Parse from headers
let accept = Accept.from(request.headers.get('Accept'))

accept.mediaTypes // ['text/html', 'text/*']
accept.weights // [1, 0.9]
accept.accepts('text/html') // true
accept.accepts('text/plain') // true (matches text/*)
accept.accepts('image/jpeg') // false
accept.getWeight('text/plain') // 1 (matches text/*)
accept.getPreferred(['text/html', 'text/plain']) // 'text/html'

// Iterate
for (let [mediaType, quality] of accept) {
  // ...
}

// Modify and set header
accept.set('application/json', 0.8)
accept.delete('text/*')
headers.set('Accept', accept.toString())

// Construct directly
new Accept('text/html, text/*;q=0.9')
new Accept({ 'text/html': 1, 'text/*': 0.9 })
new Accept(['text/html', ['text/*', 0.9]])

// Use class for type safety when setting Headers values
// via Accept's `.toString()` method
let requestHeaders = new Headers({
  Accept: new Accept({ 'text/html': 1, 'application/json': 0.8 }).toString(),
})
requestHeaders.set('Accept', new Accept({ 'text/html': 1, 'application/json': 0.8 }).toString())

Accept-Encoding

Parse, manipulate and stringify Accept-Encoding headers.

Implements Map<encoding, quality>.

import { AcceptEncoding } from 'remix/headers'

// Parse from headers
let acceptEncoding = AcceptEncoding.from(request.headers.get('Accept-Encoding'))

acceptEncoding.encodings // ['gzip', 'deflate']
acceptEncoding.weights // [1, 0.8]
acceptEncoding.accepts('gzip') // true
acceptEncoding.accepts('br') // false
acceptEncoding.getWeight('gzip') // 1
acceptEncoding.getPreferred(['gzip', 'deflate', 'br']) // 'gzip'

// Modify and set header
acceptEncoding.set('br', 1)
acceptEncoding.delete('deflate')
headers.set('Accept-Encoding', acceptEncoding.toString())

// Construct directly
new AcceptEncoding('gzip, deflate;q=0.8')
new AcceptEncoding({ gzip: 1, deflate: 0.8 })

// Use class for type safety when setting Headers values
// via AcceptEncoding's `.toString()` method
let requestHeaders = new Headers({
  'Accept-Encoding': new AcceptEncoding({ gzip: 1, br: 0.9 }).toString(),
})
requestHeaders.set('Accept-Encoding', new AcceptEncoding({ gzip: 1, br: 0.9 }).toString())

Accept-Language

Parse, manipulate and stringify Accept-Language headers.

Implements Map<language, quality>.

import { AcceptLanguage } from 'remix/headers'

// Parse from headers
let acceptLanguage = AcceptLanguage.from(request.headers.get('Accept-Language'))

acceptLanguage.languages // ['en-us', 'en']
acceptLanguage.weights // [1, 0.9]
acceptLanguage.accepts('en-US') // true
acceptLanguage.accepts('en-GB') // true (matches en)
acceptLanguage.getWeight('en-GB') // 1 (matches en)
acceptLanguage.getPreferred(['en-US', 'en-GB', 'fr']) // 'en-US'

// Modify and set header
acceptLanguage.set('fr', 0.5)
acceptLanguage.delete('en')
headers.set('Accept-Language', acceptLanguage.toString())

// Construct directly
new AcceptLanguage('en-US, en;q=0.9')
new AcceptLanguage({ 'en-US': 1, en: 0.9 })

// Use class for type safety when setting Headers values
// via AcceptLanguage's `.toString()` method
let requestHeaders = new Headers({
  'Accept-Language': new AcceptLanguage({ 'en-US': 1, fr: 0.5 }).toString(),
})
requestHeaders.set('Accept-Language', new AcceptLanguage({ 'en-US': 1, fr: 0.5 }).toString())

Cache-Control

Parse, manipulate and stringify Cache-Control headers.

import { CacheControl } from 'remix/headers'

// Parse from headers
let cacheControl = CacheControl.from(response.headers.get('Cache-Control'))

cacheControl.public // true
cacheControl.maxAge // 3600
cacheControl.sMaxage // 7200
cacheControl.noCache // undefined
cacheControl.noStore // undefined
cacheControl.noTransform // undefined
cacheControl.mustRevalidate // undefined
cacheControl.immutable // undefined

// Modify and set header
cacheControl.maxAge = 7200
cacheControl.immutable = true
headers.set('Cache-Control', cacheControl.toString())

// Construct directly
new CacheControl('public, max-age=3600')
new CacheControl({ public: true, maxAge: 3600 })

// Use class for type safety when setting Headers values
// via CacheControl's `.toString()` method
let responseHeaders = new Headers({
  'Cache-Control': new CacheControl({ public: true, maxAge: 3600 }).toString(),
})
responseHeaders.set('Cache-Control', new CacheControl({ public: true, maxAge: 3600 }).toString())

Content-Disposition

Parse, manipulate and stringify Content-Disposition headers.

import { ContentDisposition } from 'remix/headers'

// Parse from headers
let contentDisposition = ContentDisposition.from(response.headers.get('Content-Disposition'))

contentDisposition.type // 'attachment'
contentDisposition.filename // 'example.pdf'
contentDisposition.filenameSplat // "UTF-8''%E4%BE%8B%E5%AD%90.pdf"
contentDisposition.preferredFilename // '例子.pdf' (decoded from filename*)

// Modify and set header
contentDisposition.filename = 'download.pdf'
headers.set('Content-Disposition', contentDisposition.toString())

// Construct directly
new ContentDisposition('attachment; filename="example.pdf"')
new ContentDisposition({ type: 'attachment', filename: 'example.pdf' })

// Use class for type safety when setting Headers values
// via ContentDisposition's `.toString()` method
let responseHeaders = new Headers({
  'Content-Disposition': new ContentDisposition({
    type: 'attachment',
    filename: 'example.pdf',
  }).toString(),
})
responseHeaders.set(
  'Content-Disposition',
  new ContentDisposition({ type: 'attachment', filename: 'example.pdf' }).toString(),
)

Filename Safety

Content-Disposition filenames received from clients are untrusted input. filename and filenameSplat expose parsed parameter values; preferredFilename selects and decodes filename* when available, falling back to filename. These APIs preserve filename metadata without sanitizing it for filesystem use, so values can contain path separators, .. segments, or absolute paths.

Do not use any of these values, or a File.name derived from them, directly as a filesystem path or join them to an upload directory. Generate a storage name in your application, such as crypto.randomUUID(), within a directory you control, and keep the submitted filename only as metadata. The same rule applies to filenames received from remote servers. See RFC 6266, section 4.3 and RFC 7578, section 4.2.

Content-Range

Parse, manipulate and stringify Content-Range headers.

import { ContentRange } from 'remix/headers'

// Parse from headers
let contentRange = ContentRange.from(response.headers.get('Content-Range'))

contentRange.unit // "bytes"
contentRange.start // 200
contentRange.end // 1000
contentRange.size // 67589

// Unsatisfied range
let unsatisfied = ContentRange.from('bytes */67589')
unsatisfied.start // null
unsatisfied.end // null
unsatisfied.size // 67589

// Construct directly
new ContentRange({ unit: 'bytes', start: 0, end: 499, size: 1000 })

// Use class for type safety when setting Headers values
// via ContentRange's `.toString()` method
let headers = new Headers({
  'Content-Range': new ContentRange({ unit: 'bytes', start: 0, end: 499, size: 1000 }).toString(),
})
headers.set(
  'Content-Range',
  new ContentRange({ unit: 'bytes', start: 0, end: 499, size: 1000 }).toString(),
)

Content-Type

Parse, manipulate and stringify Content-Type headers.

import { ContentType } from 'remix/headers'

// Parse from headers
let contentType = ContentType.from(request.headers.get('Content-Type'))

contentType.mediaType // "text/html"
contentType.charset // "utf-8"
contentType.boundary // undefined (or boundary string for multipart)

// Modify and set header
contentType.charset = 'iso-8859-1'
headers.set('Content-Type', contentType.toString())

// Construct directly
new ContentType('text/html; charset=utf-8')
new ContentType({ mediaType: 'text/html', charset: 'utf-8' })

// Use class for type safety when setting Headers values
// via ContentType's `.toString()` method
let responseHeaders = new Headers({
  'Content-Type': new ContentType({ mediaType: 'text/html', charset: 'utf-8' }).toString(),
})
responseHeaders.set(
  'Content-Type',
  new ContentType({ mediaType: 'text/html', charset: 'utf-8' }).toString(),
)

Parse, manipulate and stringify Cookie headers.

Implements an ordered list of name/value pairs. Duplicate cookie names are preserved, such as when cookies with the same name were set for different paths.

import { Cookie } from 'remix/headers'

// Parse from headers
let cookie = Cookie.from(request.headers.get('Cookie'))

cookie.get('session_id') // 'abc123'
cookie.getAll('session_id') // ['abc123']
cookie.get('theme') // 'dark'
cookie.has('session_id') // true
cookie.size // 2

// Iterate
for (let [name, value] of cookie) {
  // ...
}

// Modify and set header
cookie.set('theme', 'light')
cookie.append('session_id', 'def456')
cookie.delete('session_id')
headers.set('Cookie', cookie.toString())

// Construct directly
new Cookie('session_id=abc123; theme=dark')
new Cookie({ session_id: 'abc123', theme: 'dark' })
new Cookie([
  ['session_id', 'abc123'],
  ['theme', 'dark'],
])

// Use class for type safety when setting Headers values
// via Cookie's `.toString()` method
let requestHeaders = new Headers({
  Cookie: new Cookie({ session_id: 'abc123', theme: 'dark' }).toString(),
})
requestHeaders.set('Cookie', new Cookie({ session_id: 'abc123', theme: 'dark' }).toString())

If-Match

Parse, manipulate and stringify If-Match headers.

import { IfMatch } from 'remix/headers'

// Parse from headers
let ifMatch = IfMatch.from(request.headers.get('If-Match'))

ifMatch.tags // ['"67ab43"', '"54ed21"']
ifMatch.has('"67ab43"') // true
ifMatch.matches('"67ab43"') // true (checks precondition)
ifMatch.matches('"abc123"') // false

// Note: Uses strong comparison only (weak ETags never match)
let weak = IfMatch.from('W/"67ab43"')
weak.matches('W/"67ab43"') // false

// Modify and set header
ifMatch.tags.push('"newetag"')
ifMatch.tags = ifMatch.tags.filter((tag) => tag !== '"67ab43"')
headers.set('If-Match', ifMatch.toString())

// Construct directly
new IfMatch(['abc123', 'def456'])

// Use class for type safety when setting Headers values
// via IfMatch's `.toString()` method
let requestHeaders = new Headers({
  'If-Match': new IfMatch(['"abc123"', '"def456"']).toString(),
})
requestHeaders.set('If-Match', new IfMatch(['"abc123"', '"def456"']).toString())

If-None-Match

Parse, manipulate and stringify If-None-Match headers.

import { IfNoneMatch } from 'remix/headers'

// Parse from headers
let ifNoneMatch = IfNoneMatch.from(request.headers.get('If-None-Match'))

ifNoneMatch.tags // ['"67ab43"', '"54ed21"']
ifNoneMatch.has('"67ab43"') // true
ifNoneMatch.matches('"67ab43"') // true

// Supports weak comparison (unlike If-Match)
let weak = IfNoneMatch.from('W/"67ab43"')
weak.matches('W/"67ab43"') // true

// Modify and set header
ifNoneMatch.tags.push('"newetag"')
ifNoneMatch.tags = ifNoneMatch.tags.filter((tag) => tag !== '"67ab43"')
headers.set('If-None-Match', ifNoneMatch.toString())

// Construct directly
new IfNoneMatch(['abc123'])

// Use class for type safety when setting Headers values
// via IfNoneMatch's `.toString()` method
let requestHeaders = new Headers({
  'If-None-Match': new IfNoneMatch(['"abc123"']).toString(),
})
requestHeaders.set('If-None-Match', new IfNoneMatch(['"abc123"']).toString())

If-Range

Parse, manipulate and stringify If-Range headers.

import { IfRange } from 'remix/headers'

// Parse from headers
let ifRange = IfRange.from(request.headers.get('If-Range'))

// With HTTP date
ifRange.matches({ lastModified: 1609459200000 }) // true
ifRange.matches({ lastModified: new Date('2021-01-01') }) // true

// With ETag
let etagHeader = IfRange.from('"67ab43"')
etagHeader.matches({ etag: '"67ab43"' }) // true

// An absent header lets the range request proceed unconditionally
let absent = IfRange.from(null)
absent.matches({ etag: '"any"' }) // true

// Empty values retain the same unconditional matching behavior
let empty = IfRange.from('')
empty.matches({ etag: '"any"' }) // true

// Construct directly
new IfRange('"abc123"')

// Use class for type safety when setting Headers values
// via IfRange's `.toString()` method
let headers = new Headers({
  'If-Range': new IfRange('"abc123"').toString(),
})
headers.set('If-Range', new IfRange('"abc123"').toString())

Range

Parse, manipulate and stringify Range headers.

import { Range } from 'remix/headers'

// Parse from headers
let range = Range.from(request.headers.get('Range'))

range.unit // "bytes"
range.ranges // [{ start: 200, end: 1000 }]
range.canSatisfy(2000) // true
range.canSatisfy(500) // false
range.normalize(2000) // [{ start: 200, end: 1000 }]

// Multiple ranges
let multi = Range.from('bytes=0-499, 1000-1499')
multi.ranges.length // 2

// Suffix range (last N bytes)
let suffix = Range.from('bytes=-500')
suffix.normalize(2000) // [{ start: 1500, end: 1999 }]

// Construct directly
new Range({ unit: 'bytes', ranges: [{ start: 0, end: 999 }] })

// Use class for type safety when setting Headers values
// via Range's `.toString()` method
let headers = new Headers({
  Range: new Range({ unit: 'bytes', ranges: [{ start: 0, end: 999 }] }).toString(),
})
headers.set('Range', new Range({ unit: 'bytes', ranges: [{ start: 0, end: 999 }] }).toString())

Parse, manipulate and stringify Set-Cookie headers.

import { SetCookie } from 'remix/headers'

// Parse from headers
let setCookie = SetCookie.from(response.headers.get('Set-Cookie'))

setCookie.name // "session_id"
setCookie.value // "abc"
setCookie.path // "/"
setCookie.httpOnly // true
setCookie.secure // true
setCookie.domain // undefined
setCookie.maxAge // undefined
setCookie.expires // undefined
setCookie.sameSite // undefined

// Modify and set header
setCookie.maxAge = 3600
setCookie.sameSite = 'Strict'
headers.set('Set-Cookie', setCookie.toString())

// Construct directly
new SetCookie('session_id=abc; Path=/; HttpOnly; Secure')
new SetCookie({
  name: 'session_id',
  value: 'abc',
  path: '/',
  httpOnly: true,
  secure: true,
})

// Use class for type safety when setting Headers values
// via SetCookie's `.toString()` method
let responseHeaders = new Headers({
  'Set-Cookie': new SetCookie({ name: 'session_id', value: 'abc', httpOnly: true }).toString(),
})
responseHeaders.set(
  'Set-Cookie',
  new SetCookie({ name: 'session_id', value: 'abc', httpOnly: true }).toString(),
)

Vary

Parse, manipulate and stringify Vary headers.

Implements Set<headerName>.

import { Vary } from 'remix/headers'

// Parse from headers
let vary = Vary.from(response.headers.get('Vary'))

vary.headerNames // ['accept-encoding', 'accept-language']
vary.has('Accept-Encoding') // true (case-insensitive)
vary.size // 2

// Modify and set header
vary.add('User-Agent')
vary.delete('Accept-Language')
headers.set('Vary', vary.toString())

// Construct directly
new Vary('Accept-Encoding, Accept-Language')
new Vary(['Accept-Encoding', 'Accept-Language'])
new Vary({ headerNames: ['Accept-Encoding', 'Accept-Language'] })

// Use class for type safety when setting Headers values
// via Vary's `.toString()` method
let responseHeaders = new Headers({
  Vary: new Vary(['Accept-Encoding', 'Accept-Language']).toString(),
})
responseHeaders.set('Vary', new Vary(['Accept-Encoding', 'Accept-Language']).toString())

Raw Headers

Parse and stringify raw HTTP header strings.

import { parse, stringify } from 'remix/headers'

let headers = parse('Content-Type: text/html\r\nCache-Control: no-cache')
headers.get('Content-Type') // 'text/html'
headers.get('Cache-Control') // 'no-cache'

stringify(headers)
// 'Content-Type: text/html\r\nCache-Control: no-cache'