Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns
Node.js res.setHeader() method
Reference for response.setHeader() and its companions getHeader(), hasHeader(), removeHeader() and appendHeader(): multiple values, Set-Cookie arrays and errors.
res.setHeader(name, value) sets a single response header. It can be called several times, from different places in your code, until the headers are sent. Setting a header that already exists replaces it.
Header names are case-insensitive, and Node remembers them in lower case for the getters. A value is a string, a number, or an array of strings, which sends the header several times. That is how you send more than one Set-Cookie. The headers go out when the first part of the body is written, or with writeHead().
import http from "node:http"; http.createServer((req, res) => { res.setHeader("Content-Type", "text/html; charset=utf-8"); res.setHeader("Set-Cookie", ["a=1; HttpOnly", "b=2; Secure"]); res.end("<p>hi</p>"); });
Try it
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.
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
res.setHeader(name: string, value: string | number | readonly string[]): this res.getHeader(name: string): string | number | string[] | undefined res.getHeaders(): object // null-prototype object, lower-case names res.getHeaderNames(): string[] res.hasHeader(name: string): boolean res.removeHeader(name: string): void res.appendHeader(name: string, value: string | readonly string[]): this
| Name | Description |
|---|---|
name |
Header name. Must be a valid HTTP token: letters, digits and characters such as - and _, no spaces. |
value |
A string, a number, or an array of strings for repeated headers. |
Returns: setHeader() and appendHeader() return the response so calls can be chained. Getters return what was stored, with names in lower case.
Errors and edge cases:
- Setting a header after the headers were sent throws
ERR_HTTP_HEADERS_SENT. - An invalid name throws
ERR_INVALID_HTTP_TOKEN. - A value containing a line break or other forbidden character throws
ERR_INVALID_CHAR, which blocks header-injection attacks. - A value of
undefinedthrowsERR_HTTP_INVALID_HEADER_VALUE. getHeader()returns the stored form: a number stays a number, an array stays an array.
Usage notes
- Use an array for several
Set-Cookieheaders. Joining cookies with commas is wrong, because cookie dates contain commas. setHeader()replaces;appendHeader()(added in Node.js 18.3) adds a further value for the same name.res.writeHead()headers overridesetHeader()ones with the same name;res.getHeaders()shows only the headers set throughsetHeader()untilwriteHead()merges them.- Set
Content-Typewith a charset for text (text/plain; charset=utf-8), andCache-Controlexplicitly for anything cacheable. - Header names are case-insensitive, but Node sends them as you wrote them for HTTP/1.1. HTTP/2 lower-cases everything, so never depend on casing.
- Check
res.headersSentbefore attempting to change headers in error handlers. - Do not copy untrusted input into a header name, and be careful with values such as
Location, which can enable open redirects.