Skip to main content
Lark supports two transport protocols for client-server communication. The SDK defaults to WebSocket, but you can opt in to WebTransport for lower latency in supported browsers.

​
WebSocket

WebSocket is the default transport. It works everywhere: all browsers, Node.js, React Native, and any environment that supports standard WebSocket connections.
URLwss://{projectId}.larkdb.net/ws
DeliveryReliable, ordered TCP delivery. Every message arrives, in order.
CompatibilityUniversal. If your client can make a network connection, it can use WebSocket.
WebSocket is a mature, battle-tested protocol. For most applications, it’s the only transport you need.

​
WebTransport

WebTransport is a modern protocol built on HTTP/3 and QUIC. It’s available in newer browsers and provides meaningful advantages for real-time applications.
URLhttps://{projectId}.larkdb.net:{port}/wt (port randomly assigned from 7778-7809 for load balancing)
DeliveryQUIC streams for reliable data, plus UDP datagrams for volatile paths.
CompatibilityChrome 97+, Edge 97+, Firefox 114+. Not yet available in Safari, Node.js, or React Native.

​
WebTransport advantages

WebTransport has two key advantages over WebSocket: No head-of-line blocking. With WebSocket (TCP), if one packet is lost, every subsequent packet waits until the lost one is retransmitted. A dropped packet carrying a chat message stalls cursor updates, game state, everything. With WebTransport (QUIC), each stream is independent. A lost packet on one stream doesn’t block other streams. UDP datagrams for volatile data. Volatile writes over WebTransport use UDP datagrams, providing unreliable, unordered delivery with zero retransmission overhead. For data like cursor positions where you only care about the latest value, this is ideal. A lost datagram is irrelevant because a newer one is already on the way.
These advantages matter most under packet loss, which is common on mobile networks, congested Wi-Fi, and cross-continent connections. On a clean local network, WebSocket and WebTransport perform similarly.

​
Transport selection

By default, the SDK uses WebSocket. To use WebTransport, set the transport option explicitly: 
// Default — WebSocket only
const db = new LarkDatabase('my-project/my-database', {
  anonymous: true,
});

// Try WebTransport first, fall back to WebSocket
const db = new LarkDatabase('my-project/my-database', {
  anonymous: true,
  transport: 'auto',
});

// Force WebTransport only (will fail if not supported)
const db = new LarkDatabase('my-project/my-database', {
  anonymous: true,
  transport: 'webtransport',
});

// Auto with a custom timeout for the WebTransport attempt
const db = new LarkDatabase('my-project/my-database', {
  anonymous: true,
  transport: 'auto',
  webTransportTimeout: 5000, // 5 seconds (default is 2 seconds)
});
In 'auto' mode, the SDK tries WebTransport first. If the connection fails or doesn’t establish within webtransportTimeout milliseconds, it falls back to WebSocket transparently.

​
When to prefer WebTransport

Choose WebTransport when:
  • Your app uses volatile paths for game state, cursors, or other high-frequency data. The UDP datagram support gives you faster, lower-overhead delivery.
  • Your users are on modern browsers (Chrome, Edge, or Firefox).
  • Your app is latency-sensitive and your users may be on spotty connections where head-of-line blocking hurts.

​
When WebSocket is fine

WebSocket is the right choice for most applications. It’s mature, universal, and performant. You won’t notice a difference unless you’re pushing high-frequency volatile updates or operating under significant packet loss. Stick with the default WebSocket when:
  • Your app doesn’t use volatile paths.
  • You need to support Safari, Node.js, or React Native.
  • Your users are on reliable connections.
  • You just want things to work everywhere without thinking about it.
If you want the best of both worlds, set transport: 'auto'. Your Chrome and Edge users get the benefits of WebTransport, and everyone else gets reliable WebSocket.

​
What’s next

Volatile paths

High-frequency data that takes full advantage of WebTransport datagrams.

Connecting

Configure transports, timeouts, and connection lifecycle in the Lark SDK.