Headers Overview

HTTP headers are strings with specific formats -- comma-separated lists, key-value parameters, quality values, date stamps. Parsing and building them by hand is tedious and error-prone.

The headers package provides typed classes for 14 common HTTP headers. Each class can parse a header string into a structured object, and stringify it back. Instead of string manipulation, you work with typed properties like cache.maxAge, accept.negotiate(['text/html', 'application/json']), or cookie.get('session').

Supported Headers

Class	HTTP Header	Category
Accept	Accept	Content negotiation
AcceptEncoding	Accept-Encoding	Content negotiation
AcceptLanguage	Accept-Language	Content negotiation
CacheControl	Cache-Control	Caching
ContentType	Content-Type	Content
ContentDisposition	Content-Disposition	Content
ContentRange	Content-Range	Content
Cookie	Cookie	Cookies
SetCookie	Set-Cookie	Cookies
IfMatch	If-Match	Conditional
IfNoneMatch	If-None-Match	Conditional
IfRange	If-Range	Conditional
Range	Range	Range requests
Vary	Vary	Caching

Quick Example

import { CacheControl, Accept, SetCookie } from 'remix/headers'

// Parse a Cache-Control header
let cache = CacheControl.parse('public, max-age=3600')
console.log(cache.maxAge)    // 3600
console.log(cache.public)    // true

// Build a Cache-Control header
let newCache = new CacheControl({ public: true, maxAge: 86400, immutable: true })
console.log(newCache.stringify()) // 'public, max-age=86400, immutable'

// Content negotiation
let accept = Accept.parse('text/html, application/json;q=0.9')
accept.negotiate(['text/html', 'application/json']) // 'text/html'

// Set a cookie
let cookie = new SetCookie('session', 'abc123', {
  httpOnly: true,
  secure: true,
  sameSite: 'lax',
  maxAge: 86400,
})
console.log(cookie.stringify())
// 'session=abc123; HttpOnly; Secure; SameSite=Lax; Max-Age=86400'

Common Pattern

Every header class follows the same three-part pattern:

1. ClassName.parse(headerString) -- Static method that parses a raw header string into a typed instance.
2. new ClassName(values) -- Constructor that creates an instance from typed values.
3. instance.stringify() -- Serializes the instance back to a header string.

This consistency means once you learn one class, you know how to use all of them.

Key Concepts

• Content negotiation -- The process where a client says what formats it accepts (via Accept, Accept-Encoding, Accept-Language) and the server picks the best match. The negotiate method handles this for you.
• Quality values -- A number between 0 and 1 (written as q=0.9 in headers) that indicates preference. Higher means more preferred.
• Cache directives -- Instructions in Cache-Control that tell browsers and CDNs how long to cache a response and under what conditions.
• Range requests -- Clients can request a portion of a file using the Range header. Servers respond with Content-Range and status 206.

Related

• response -- Response helpers that use these header classes internally
• cookie -- Lower-level cookie parsing (the headers package covers Cookie and SetCookie headers)
• API Reference -- Full API documentation for all 14 classes