Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Web APIs in Node.js

Node.js Headers class

Reference for the Headers class in Node.js: create, read, append, set and delete HTTP headers, iterate them, and handle multiple Set-Cookie values.

Headers is a collection of HTTP header names and values with case-insensitive lookup. It is a global class that fetch(), Request and Response use for their headers properties, and you can create your own to build the headers of an outgoing request.

Names are stored in lower case, and iteration is sorted by name. If a header occurs several times, get() joins the values with a comma and a space, which is the HTTP rule for repeated headers. The one exception is Set-Cookie, which can not be joined safely, so there is a separate method, getSetCookie(), that returns every cookie line.

NODE
const headers = new Headers({ 'Content-Type': 'text/plain' });
headers.append('Accept', 'text/html');
console.log(headers.get('content-type')); // text/plain

Try it

Node.js Creating, reading and changing headers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Iteration, cookies and validation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
new Headers([init])

init is another Headers, an array of [name, value] pairs, or a plain object of strings.

Method Description
append(name, value) Add a value. If the name exists, the new value is added to the existing ones.
set(name, value) Replace every value of that name with this one.
get(name) The values joined with ', ', or null when the header is absent.
getSetCookie() An array with one string per Set-Cookie header (empty when there are none).
has(name) true if the header exists.
delete(name) Remove the header. Missing names are ignored.
entries(), keys(), values(), forEach(cb), [Symbol.iterator]() Iterate sorted, lower-case names with combined values (one entry per cookie for Set-Cookie).

Returns: append(), set(), delete() and forEach() return undefined; the others return the values described above.

Errors: TypeError for an invalid name (empty, containing spaces or characters outside the HTTP token set) or an invalid value (containing a newline or null byte), and when a pair array does not have exactly two items. Headers belonging to a Request or Response with a guard, such as an immutable response from fetch(), throw TypeError on writes.

Usage notes

  • Names are case-insensitive, stored lower case. HTTP/2 requires lower case, and Headers matches that, so do not rely on the original capitalization of a name.
  • Values are trimmed of leading and trailing whitespace on append() and set().
  • get() returns null, not undefined, when a header is missing, and a string (possibly empty) otherwise.
  • Use getSetCookie() for cookies. get('set-cookie') joins cookies with commas, but cookie dates also contain commas, so the result cannot be split reliably.
  • Responses from fetch() are read-only; to change a header, copy it with new Headers(response.headers), or build a new Response.
  • Plain objects are not Headers. Object.fromEntries(headers) makes an object with lower-case keys; new Headers(obj) goes the other way. Repeated headers are joined when iterated, except cookies.
  • Node servers use another API. The http module's req.headers is a plain object of lower-case names, and res.setHeader() has its own rules; convert with new Headers(req.headers) where values are strings (array values need append()).
  • getSetCookie() was added in Node 19.7 and 18.15.