{ "type": "module", "source": "doc/api/best-practices-migrating-from-v7-to-v8.md", "modules": [ { "textRaw": "Migrating from Undici 7 to 8", "name": "migrating_from_undici_7_to_8", "type": "module", "desc": "

This guide covers the changes you are most likely to hit when upgrading an\napplication or library from Undici v7 to v8.

", "modules": [ { "textRaw": "Before you upgrade", "name": "before_you_upgrade", "type": "module", "desc": "", "displayName": "Before you upgrade" }, { "textRaw": "1. Update your Node.js version", "name": "1._update_your_node.js_version", "type": "module", "desc": "

Undici v8 requires Node.js >= 22.19.0.

\n

If you are still on Node.js 20 or an older Node.js 22 release, upgrade Node.js\nfirst:

\n
node -v\n
\n

If that command prints a version lower than v22.19.0, upgrade Node.js before\ninstalling Undici v8.

", "displayName": "1. Update your Node.js version" }, { "textRaw": "2. Migrate custom dispatcher handlers to the v2 API", "name": "2._migrate_custom_dispatcher_handlers_to_the_v2_api", "type": "module", "desc": "

Undici v8 uses the newer dispatcher handler API consistently.

\n

If you implemented custom dispatchers, interceptors, or wrappers around\ndispatch(), update legacy callbacks such as onConnect, onHeaders, and\nonComplete to the newer callback names.

", "modules": [ { "textRaw": "Old handler callbacks vs. v8 callbacks", "name": "old_handler_callbacks_vs._v8_callbacks", "type": "module", "desc": "\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Undici 7 styleUndici 8 style
onConnect(abort, context)onRequestStart(controller, context)
onHeaders(statusCode, rawHeaders, resume, statusText)onResponseStart(controller, statusCode, headers, statusText)
onData(chunk)onResponseData(controller, chunk)
onComplete(trailers)onResponseEnd(controller, trailers)
onError(err)onResponseError(controller, err)
onUpgrade(statusCode, rawHeaders, socket)onRequestUpgrade(controller, statusCode, headers, socket)
", "displayName": "Old handler callbacks vs. v8 callbacks" }, { "textRaw": "Example", "name": "example", "type": "module", "desc": "

Before:

\n
client.dispatch(options, {\n  onConnect (abort) {\n    this.abort = abort\n  },\n  onHeaders (statusCode, headers, resume) {\n    this.resume = resume\n    return true\n  },\n  onData (chunk) {\n    chunks.push(chunk)\n    return true\n  },\n  onComplete (trailers) {\n    console.log(trailers)\n  },\n  onError (err) {\n    console.error(err)\n  }\n})\n
\n

After:

\n
client.dispatch(options, {\n  onRequestStart (controller) {\n    this.controller = controller\n  },\n  onResponseStart (controller, statusCode, headers, statusText) {\n    console.log(statusCode, statusText, headers)\n  },\n  onResponseData (controller, chunk) {\n    chunks.push(chunk)\n  },\n  onResponseEnd (controller, trailers) {\n    console.log(trailers)\n  },\n  onResponseError (controller, err) {\n    console.error(err)\n  }\n})\n
", "displayName": "Example" }, { "textRaw": "Pause, resume, and abort now go through the controller", "name": "pause,_resume,_and_abort_now_go_through_the_controller", "type": "module", "desc": "

In Undici v7, legacy handlers could return false or keep references to\nabort() and resume() callbacks. In Undici v8, use the controller instead:

\n
onRequestStart (controller) {\n  this.controller = controller\n}\n\nonResponseData (controller, chunk) {\n  controller.pause()\n  setImmediate(() => controller.resume())\n}\n\nonResponseError (controller, err) {\n  controller.abort(err)\n}\n
", "displayName": "Pause, resume, and abort now go through the controller" }, { "textRaw": "Raw headers and trailers moved to the controller", "name": "raw_headers_and_trailers_moved_to_the_controller", "type": "module", "desc": "

If you need the raw header arrays, read them from the controller:

\n", "displayName": "Raw headers and trailers moved to the controller" } ], "displayName": "2. Migrate custom dispatcher handlers to the v2 API" }, { "textRaw": "3. Update `onBodySent()` handlers", "name": "3._update_`onbodysent()`_handlers", "type": "module", "desc": "

If you implemented onBodySent(), note that its signature changed.

\n

Before, handlers received counters:

\n
onBodySent (chunkSize, totalBytesSent) {}\n
\n

In Undici v8, handlers receive the actual chunk:

\n
onBodySent (chunk) {}\n
\n

If you need a notification that the whole body has been sent, use\nonRequestSent():

\n
onRequestSent () {\n  console.log('request body fully sent')\n}\n
", "displayName": "3. Update `onBodySent()` handlers" }, { "textRaw": "4. If you need HTTP/1.1 only, disable HTTP/2 explicitly", "name": "4._if_you_need_http/1.1_only,_disable_http/2_explicitly", "type": "module", "desc": "

Undici v8 enables HTTP/2 by default when a TLS server negotiates it via ALPN.

\n

If your application depends on HTTP/1.1-specific behavior, set allowH2: false\nexplicitly.

\n

Before:

\n
const client = new Client('https://example.com')\n
\n

After, to keep HTTP/1.1 only:

\n
const client = new Client('https://example.com', {\n  allowH2: false\n})\n
\n

The same applies when you configure an Agent:

\n
const agent = new Agent({\n  allowH2: false\n})\n
", "displayName": "4. If you need HTTP/1.1 only, disable HTTP/2 explicitly" }, { "textRaw": "5. Use real `Blob` and `File` instances", "name": "5._use_real_`blob`_and_`file`_instances", "type": "module", "desc": "

Undici v8 no longer accepts fake Blob-like values that only imitate Blob or\nFile via properties such as Symbol.toStringTag.

\n

If you were passing custom objects that looked like Blobs, replace them with\nactual Blob or File instances:

\n
const body = new Blob(['hello'])\n
", "displayName": "5. Use real `Blob` and `File` instances" }, { "textRaw": "6. Avoid depending on the internal global dispatcher symbol", "name": "6._avoid_depending_on_the_internal_global_dispatcher_symbol", "type": "module", "desc": "

setGlobalDispatcher() and getGlobalDispatcher() remain the public APIs and\nshould continue to be used.

\n

Internally, Undici v8 stores its dispatcher under\nSymbol.for('undici.globalDispatcher.2') and mirrors a v1-compatible wrapper\nfor legacy consumers such as Node.js built-in fetch.

\n

If your code was reading or writing Symbol.for('undici.globalDispatcher.1')\ndirectly, migrate to the public APIs instead:

\n
import { setGlobalDispatcher, getGlobalDispatcher, Agent } from 'undici'\n\nsetGlobalDispatcher(new Agent())\nconst dispatcher = getGlobalDispatcher()\n
\n

If you must expose a dispatcher to legacy v1 handler consumers, wrap it with\nDispatcher1Wrapper:

\n
import { Agent, Dispatcher1Wrapper } from 'undici'\n\nconst legacyCompatibleDispatcher = new Dispatcher1Wrapper(new Agent())\n
", "displayName": "6. Avoid depending on the internal global dispatcher symbol" }, { "textRaw": "7. Verify the upgrade", "name": "7._verify_the_upgrade", "type": "module", "desc": "

After moving to Undici v8, it is worth checking these paths in your test suite:

\n", "displayName": "7. Verify the upgrade" }, { "textRaw": "Related documentation", "name": "related_documentation", "type": "module", "desc": "", "displayName": "Related documentation" } ], "displayName": "Migrating from Undici 7 to 8" } ] }