Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns

Node.js res.writeEarlyHints() method

Reference for response.writeEarlyHints() in Node.js: send an interim 103 response with Link headers so browsers can preload assets before the real response.

response.writeEarlyHints(hints[, callback]) sends an interim 103 Early Hints response on a server response, before the final status line and body. The link entry of hints is validated and sent as a Link header. A browser that receives it can start preloading stylesheets, scripts or fonts, or opening connections, while your server is still busy producing the real page.

Interim responses are a normal part of HTTP/1.1: a response may consist of several 1xx messages followed by exactly one final message. Calling writeEarlyHints() does not end the response, so you still call writeHead() or end() afterwards.

NODE
res.writeEarlyHints({
  link: '</style.css>; rel=preload; as=style',
});

Try it

Node.js Receiving a 103 on the client

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 Extra headers and the callback

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
response.writeEarlyHints(hints, callback)
// hints: { link: string | string[], [header: string]: string | string[] }
// callback: () => void   (optional)
Name Description
hints Object whose keys are header names. The usual (and useful) key is link, a string or array of strings in <url>; rel=... form. Other keys are sent as extra headers on the 103 message.
callback Optional function called once the interim response has been written.

Returns: undefined.

Errors: throws ERR_INVALID_ARG_TYPE when hints is not an object, ERR_INVALID_ARG_VALUE when a link value is not in the <url>; params form, and ERR_INVALID_HTTP_TOKEN for an invalid header name. It must be called before writeHead() or end(); once the final head has been sent there is nothing left to hint at.

Usage notes

  • The point is parallelism. The browser downloads the hinted assets while your server computes the page. If the page is ready in a few milliseconds, the hint gains nothing.
  • Client side: http.request() and http.get() emit an 'information' event for each 1xx message, with statusCode, statusMessage, httpVersion, headers and rawHeaders. fetch() does not expose interim responses, so it only sees the final one.
  • Browsers only act on Link hints of kind preload and preconnect (and modulepreload), for top-level navigations over HTTP/2 or HTTP/3 in most browsers. Plain HTTP/1.1 support is less common; the method itself works on any HTTP version.
  • You can call it more than once, for example to send further hints as more is learned, but one call with all the links is the usual pattern.
  • Treat the hints as promises. If you hint at /app.css and the final page never uses it, the browser wasted a request. Keep the list short and accurate.
  • Proxies and CDNs may swallow or forward 103 responses depending on configuration; check your edge before depending on it.
  • Version notes: added in Node.js v18.11.0.