{ "dataset": "WebTransport API cheat sheet", "publisher": "WebTransport Day", "page": "https://webtransport.day/cheatsheet/", "title": "WebTransport API cheat sheet", "checkedOn": "2026-10-28", "sections": [ { "id": "create-a-session", "title": "Create a session", "items": [ { "title": "Connect with the WebTransport constructor", "code": "const transport = new WebTransport(\"https://example.com:4433/echo\");\nawait transport.ready; // resolves once the session is established\nconsole.log(\"connected\");", "note": "The URL must use https and an explicit port; a bad URL or a fragment throws SyntaxError. MDN currently marks this 'Baseline 2026, Newly available' (since March 2026), with a note that parts of the feature have varying support, and it is secure-context only.", "sources": [ { "title": "WebTransport() constructor (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/WebTransport" }, { "title": "WebTransport.ready (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/ready" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" }, { "title": "Trust a certificate by hash with serverCertificateHashes", "code": "const certHash = new Uint8Array(32); // placeholder: SHA-256 of your server certificate\nconst transport = new WebTransport(\"https://example.com:4433/echo\", {\n serverCertificateHashes: [{ algorithm: \"sha-256\", value: certHash }],\n});\nawait transport.ready;", "note": "Replaces Web PKI validation for this connection. MDN says the certificate must be X.509v3 with under two weeks of validity and an ECDSA P-256 key, and the option cannot be combined with allowPooling: true. Only sha-256 is defined.", "sources": [ { "title": "WebTransport() constructor (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/WebTransport" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" }, { "title": "Hint a congestion control preference", "code": "const transport = new WebTransport(\"https://example.com:4433/echo\", {\n congestionControl: \"low-latency\", // \"default\" | \"throughput\" | \"low-latency\"\n});\nawait transport.ready;\nconsole.log(transport.congestionControl); // the preference as the browser reports it", "note": "Only a hint; the browser may fall back to \"default\". MDN currently marks this 'Limited availability' (not Baseline) on the congestionControl property page, and the spec flags \"low-latency\" as a feature at risk because no browser implements a low-latency algorithm yet.", "sources": [ { "title": "WebTransport() constructor (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/WebTransport" }, { "title": "WebTransport.congestionControl (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/congestionControl" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" }, { "title": "Refuse a reliable-only fallback with requireUnreliable", "code": "const transport = new WebTransport(\"https://example.com:4433/echo\", {\n requireUnreliable: true, // do not fall back to a reliable-only (HTTP/2) session\n});\nawait transport.ready;\nconsole.log(transport.reliability); // \"pending\" before ready, then \"reliable-only\" or \"supports-unreliable\"", "note": "Defaults to false. MDN marks the reliability property page 'Limited availability' (not Baseline), while the constructor page shows 'Baseline 2026, Newly available' (since March 2026).", "sources": [ { "title": "WebTransport() constructor (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/WebTransport" }, { "title": "WebTransport.reliability (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/reliability" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" }, { "title": "Negotiate an application protocol with protocols", "code": "const transport = new WebTransport(\"https://example.com:4433/echo\", {\n protocols: [\"chat\", \"file-transfer\"], // in order of preference\n});\nawait transport.ready;\nconsole.log(transport.protocol); // the server's choice, or \"\" if it selected none", "note": "If the server supports none of the offered protocols, ready rejects. Per the spec, duplicates, empty values and values over 512 characters throw SyntaxError. The option is documented by both MDN and the W3C spec.", "sources": [ { "title": "WebTransport() constructor (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/WebTransport" }, { "title": "WebTransport API (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport_API" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" } ] }, { "id": "session-lifecycle", "title": "Session lifecycle", "items": [ { "title": "Watch ready and closed", "code": "const transport = new WebTransport(\"https://example.com:4433/echo\");\ntransport.closed\n .then(({ closeCode, reason }) => console.log(\"closed\", closeCode, reason))\n .catch((err) => console.error(\"closed abruptly\", err));\ntry {\n await transport.ready;\n} catch (err) {\n console.error(\"session failed\", err);\n}", "note": "Both promises exist from construction. closed resolves with { closeCode, reason } and rejects on unexpected closure such as a network failure. MDN currently marks this 'Baseline 2026, Newly available' (since March 2026).", "sources": [ { "title": "WebTransport.ready (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/ready" }, { "title": "WebTransport.closed (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/closed" }, { "title": "WebTransport API (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport_API" } ], "status": "verified" }, { "title": "React to draining", "code": "async function migrateOnDraining(url, oldTransport) {\n await oldTransport.draining; // fulfills when the server signals draining\n const next = new WebTransport(url);\n await next.ready;\n oldTransport.close(); // retire the old session once the new one is up\n return next;\n}", "note": "Draining is only a request: either side may keep using the session, but the app is expected to wrap up soon. The W3C spec lists draining as a session state. MDN's draining page carries no Baseline banner at the moment.", "sources": [ { "title": "WebTransport.draining (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/draining" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" }, { "title": "Close with a code and reason", "code": "transport.close({ closeCode: 17, reason: \"CloseButtonPressed\" });\nconst info = await transport.closed;\nconsole.log(info.closeCode, info.reason);", "note": "closeCode defaults to 0 and the reason is truncated to 1024 UTF-8 bytes per the spec. MDN names the parameter info; the spec calls it closeInfo. MDN currently marks this 'Baseline 2026, Newly available' (since March 2026).", "sources": [ { "title": "WebTransport.close() (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/close" }, { "title": "WebTransport.closed (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/closed" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" }, { "title": "Inspect reliability after ready", "code": "await transport.ready; // reliability is \"pending\" before this point\nif (transport.reliability === \"reliable-only\") {\n // no datagrams: stick to streams\n} else {\n // \"supports-unreliable\": datagrams are available\n}", "note": "Tells you whether the session can carry unreliable datagrams. MDN currently marks this 'Limited availability' (not Baseline).", "sources": [ { "title": "WebTransport.reliability (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/reliability" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" } ] }, { "id": "bidirectional-streams", "title": "Bidirectional streams", "items": [ { "title": "Open a stream, write, then read", "code": "const stream = await transport.createBidirectionalStream();\nconst writer = stream.writable.getWriter();\nawait writer.write(new TextEncoder().encode(\"hello\"));\nawait writer.close(); // tries to send pending data before closing\nconst reader = stream.readable.getReader();\nfor (;;) {\n const { value, done } = await reader.read();\n if (done) break;\n console.log(new TextDecoder().decode(value)); // value is a Uint8Array\n}", "note": "Assumes a server that echoes and closes its side. MDN currently marks this 'Baseline 2026, Newly available' (since March 2026) for createBidirectionalStream(), with partial-support asterisk. It rejects with InvalidStateError if the session is closed or failed.", "sources": [ { "title": "WebTransport.createBidirectionalStream() (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/createBidirectionalStream" }, { "title": "WebTransportBidirectionalStream (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportBidirectionalStream" }, { "title": "WebTransport API (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport_API" } ], "status": "verified" }, { "title": "Accept server-opened streams", "code": "const reader = transport.incomingBidirectionalStreams.getReader();\nfor (;;) {\n const { value: stream, done } = await reader.read();\n if (done) break;\n // each value is a WebTransportBidirectionalStream opened by the server\n stream.readable.pipeTo(stream.writable).catch(console.error); // echo it back\n}", "note": "incomingBidirectionalStreams is a ReadableStream of WebTransportBidirectionalStream objects. MDN currently marks this 'Baseline 2026, Newly available' (since March 2026).", "sources": [ { "title": "WebTransport.incomingBidirectionalStreams (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/incomingBidirectionalStreams" }, { "title": "WebTransportBidirectionalStream (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportBidirectionalStream" }, { "title": "ReadableStream (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream" } ], "status": "verified" }, { "title": "Prioritise streams with sendOrder", "code": "const urgent = await transport.createBidirectionalStream({ sendOrder: 10 });\nconst bulk = await transport.createBidirectionalStream({ sendOrder: 1 });\n// queued bytes on the higher sendOrder stream are sent first", "note": "MDN's createBidirectionalStream() page documents only sendOrder (an integer; its own examples pass a string). The W3C spec also lists sendGroup and waitUntilAvailable, which MDN does not describe on that page.", "sources": [ { "title": "WebTransport.createBidirectionalStream() (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/createBidirectionalStream" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" } ] }, { "id": "unidirectional-streams", "title": "Unidirectional streams", "items": [ { "title": "Send on a client-opened stream", "code": "const stream = await transport.createUnidirectionalStream(); // a WebTransportSendStream\nconst writer = stream.getWriter();\nwriter.write(new Uint8Array([65, 66, 67]));\ntry {\n await writer.close(); // tries to send all pending data first\n console.log(\"All data has been sent.\");\n} catch (error) {\n console.error(`An error occurred: ${error}`);\n}", "note": "The returned WebTransportSendStream is itself a WritableStream. MDN currently marks this 'Limited availability' (not Baseline) on the createUnidirectionalStream() page (it is also marked this way on the WebTransportSendStream page).", "sources": [ { "title": "WebTransport.createUnidirectionalStream() (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/createUnidirectionalStream" }, { "title": "WebTransportSendStream (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportSendStream" } ], "status": "verified" }, { "title": "Receive server-opened unidirectional streams", "code": "const reader = transport.incomingUnidirectionalStreams.getReader();\nfor (;;) {\n const { value: receiveStream, done } = await reader.read();\n if (done) break;\n const chunks = receiveStream.getReader(); // a WebTransportReceiveStream\n for (;;) {\n const r = await chunks.read();\n if (r.done) break;\n console.log(r.value); // Uint8Array\n }\n}", "note": "The outer loop awaits each stream in turn; handle streams concurrently in real code. MDN currently marks this 'Baseline 2026, Newly available' (since March 2026) for incomingUnidirectionalStreams, whereas the WebTransportReceiveStream page is marked 'Limited availability' (not Baseline).", "sources": [ { "title": "WebTransport.incomingUnidirectionalStreams (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/incomingUnidirectionalStreams" }, { "title": "WebTransportReceiveStream (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportReceiveStream" } ], "status": "verified" }, { "title": "Abort a send stream", "code": "const stream = await transport.createUnidirectionalStream();\nconst writer = stream.getWriter();\nwriter.write(new Uint8Array([65, 66, 67]));\nawait writer.abort(); // pending data may be discarded", "note": "With abort() the browser may discard data that has not yet been sent. Without a WebTransportError reason, the spec sends error code 0. See the Errors section for aborting with a code.", "sources": [ { "title": "WebTransport.createUnidirectionalStream() (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/createUnidirectionalStream" }, { "title": "WritableStream (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WritableStream" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" } ] }, { "id": "datagrams", "title": "Datagrams", "items": [ { "title": "Send datagrams with createWritable()", "code": "const writable =\n typeof transport.datagrams.createWritable === \"function\"\n ? transport.datagrams.createWritable()\n : transport.datagrams.writable; // deprecated and non-standard\nconst writer = writable.getWriter();\nawait writer.ready;\nwriter.write(new Uint8Array([65, 66, 67])).catch(() => {});", "note": "MDN calls the datagrams.writable fallback \"deprecated and non-standard\" and prefers createWritable(); the W3C spec text I read lists only createWritable(). MDN currently marks this 'Baseline 2026, Newly available' (since March 2026) for the datagrams property.", "sources": [ { "title": "WebTransport.datagrams (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/datagrams" }, { "title": "WebTransportDatagramDuplexStream.createWritable() (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportDatagramDuplexStream/createWritable" }, { "title": "WebTransportDatagramDuplexStream (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportDatagramDuplexStream" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" }, { "title": "Read incoming datagrams", "code": "const reader = transport.datagrams.readable.getReader();\nfor (;;) {\n const { value, done } = await reader.read();\n if (done) break;\n console.log(value); // Uint8Array\n}", "note": "Datagrams are unreliable: not guaranteed to arrive, and not in order. Only works on sessions that support unreliable transport.", "sources": [ { "title": "WebTransport.datagrams (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/datagrams" }, { "title": "WebTransportDatagramDuplexStream (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportDatagramDuplexStream" } ], "status": "verified" }, { "title": "Respect maxDatagramSize", "code": "const writer = transport.datagrams.createWritable().getWriter();\nconst payload = new Uint8Array(200);\nif (payload.byteLength <= transport.datagrams.maxDatagramSize) {\n await writer.ready;\n writer.write(payload).catch(() => {});\n}", "note": "maxDatagramSize is the largest outgoing datagram, in bytes, that may be written. It is read-only.", "sources": [ { "title": "WebTransportDatagramDuplexStream (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportDatagramDuplexStream" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" }, { "title": "Expire stale datagrams with incomingMaxAge and outgoingMaxAge", "code": "transport.datagrams.incomingMaxAge = 2000; // milliseconds\ntransport.datagrams.outgoingMaxAge = 2000;\nconsole.log(transport.datagrams.outgoingMaxAge); // null when no maximum age is set", "note": "Both are read/write and measured in milliseconds. Per the spec, 0 is stored as null, and a negative or NaN value throws RangeError.", "sources": [ { "title": "WebTransportDatagramDuplexStream (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportDatagramDuplexStream" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" }, { "title": "Datagram queue-size attributes (names differ)", "code": "const d = transport.datagrams;\nconsole.log(\"incomingHighWaterMark\" in d); // named by MDN\nconsole.log(\"incomingMaxBufferedDatagrams\" in d); // named by the W3C spec", "note": "MDN documents incomingHighWaterMark and outgoingHighWaterMark; the W3C spec text I read documents incomingMaxBufferedDatagrams and outgoingMaxBufferedDatagrams (minimum 1) instead. Probe for the name before using either.", "sources": [ { "title": "WebTransportDatagramDuplexStream (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportDatagramDuplexStream" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "draft" } ] }, { "id": "errors-and-aborting", "title": "Errors and aborting", "items": [ { "title": "Inspect a WebTransportError", "code": "try {\n await transport.ready;\n} catch (error) {\n if (error instanceof WebTransportError) {\n console.log(error.source, error.streamErrorCode); // \"stream\" | \"session\", number | null\n } else {\n throw error; // e.g. a SyntaxError for a bad URL\n }\n}", "note": "source is \"stream\" or \"session\"; streamErrorCode is null if unavailable. MDN says the code is in the range 0-255, but the W3C spec defines an unsigned long, so treat the upper bound as unsettled. MDN currently marks this 'Baseline 2026, Newly available' (since March 2026).", "sources": [ { "title": "WebTransportError (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportError" }, { "title": "WebTransportError() constructor (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportError/WebTransportError" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" }, { "title": "Abort a send stream or cancel a receive stream with a code", "code": "const send = await transport.createUnidirectionalStream();\nawait send.getWriter().abort(new WebTransportError(\"done\", { streamErrorCode: 7 }));\n\n// for a server-opened receive stream:\nawait receiveStream.getReader().cancel(new WebTransportError(\"unwanted\", { streamErrorCode: 7 }));", "note": "Per the spec, abort and cancel use the reason's streamErrorCode when the reason is a WebTransportError, else 0, and clamp to 0-4294967295. The constructor signature disagrees: the spec shows (message, { source, streamErrorCode }) while MDN shows a single init object with message and streamErrorCode.", "sources": [ { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" }, { "title": "WebTransportError() constructor (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportError/WebTransportError" }, { "title": "WebTransportError (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportError" }, { "title": "WebTransportSendStream (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportSendStream" }, { "title": "WebTransportReceiveStream (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransportReceiveStream" } ], "status": "draft" } ] }, { "id": "feature-detection", "title": "Feature detection", "items": [ { "title": "Check that WebTransport exists", "code": "if (\"WebTransport\" in window) {\n // safe to construct a WebTransport\n} else {\n // fall back to WebSocket or another transport\n}", "note": "In a worker, use typeof WebTransport !== \"undefined\" instead, since window is not defined there. The interfaces are exposed in Window and Worker contexts.", "sources": [ { "title": "WebTransport.supportsReliableOnly (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/supportsReliableOnly_static" }, { "title": "WebTransport (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" }, { "title": "Check for a secure context", "code": "if (!window.isSecureContext) {\n console.warn(\"WebTransport needs a secure context (https or localhost)\");\n}", "note": "The WebTransport interfaces are marked SecureContext, so they exist only on https pages (or localhost). In workers, check self.isSecureContext.", "sources": [ { "title": "Secure contexts (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Secure_Contexts" }, { "title": "WebTransport (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" }, { "title": "Probe members that may be missing", "code": "const hasCreateWritable = typeof transport.datagrams.createWritable === \"function\";\nconst hasCongestionControl = \"congestionControl\" in WebTransport.prototype;\nconst hasSendGroups = \"createSendGroup\" in WebTransport.prototype;\nconst canFallBackToReliableOnly = WebTransport.supportsReliableOnly; // static boolean", "note": "Treat newer members as optional. MDN currently marks congestionControl, reliability, createUnidirectionalStream(), WebTransportSendStream and WebTransportReceiveStream as 'Limited availability' (not Baseline), while the main WebTransport page shows 'Baseline 2026, Newly available' with partial-support asterisk.", "sources": [ { "title": "WebTransport (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport" }, { "title": "WebTransport.supportsReliableOnly (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/supportsReliableOnly_static" }, { "title": "WebTransport.datagrams (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/datagrams" }, { "title": "WebTransport.congestionControl (MDN)", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/congestionControl" }, { "title": "WebTransport (W3C Working Draft)", "url": "https://www.w3.org/TR/webtransport/" } ], "status": "verified" } ] } ] }