Cross-Platform WebSockets with `web_socket_channel`

WHY IT EXISTS Dart runs on multiple platforms, each with a different native WebSocket implementation: dart:html for web and dart:io for mobile, desktop, and server. Writing conditional code to handle each case is repetitive and error-prone. This package was created to provide a single, unified API that works everywhere.

THE MENTAL MODEL Think of web_socket_channel as a universal adapter for WebSockets. You plug your application logic into one side, and the package automatically connects to the correct platform-specific "outlet" on the other. You write your code once, and it runs on web, iOS, Android, and desktop without changes.

HOW IT WORKS The package's core is the WebSocketChannel class, which is a StreamChannel. You create a connection using the static method WebSocketChannel.connect(uri), which automatically uses the correct underlying implementation for the platform. This channel has two key properties: a stream for listening to incoming messages and a sink for sending outgoing messages. The sink is a special WebSocketSink that allows you to provide an optional close code and reason when calling sink.close().

WHEN TO USE IT Use this package for any Dart or Flutter application that requires real-time, bidirectional communication over WebSockets, especially when targeting multiple platforms. It's the standard solution for features like chat applications, live sports scores, or real-time collaboration tools.

WHEN NOT TO USE IT If you are building an application that will only ever run on a single platform (e.g., a server-only Dart script), you could use the platform-specific library like dart:io directly. However, using web_socket_channel adds almost no overhead and makes your code more portable if requirements change in the future.

ONE CANONICAL EXAMPLE A typical usage flow involves four steps. First, create the connection with final channel = WebSocketChannel.connect(uri). Second, and critically, wait for the connection to be established with await channel.ready. Third, listen for incoming data with channel.stream.listen((message) { ... }). Fourth, send data out with channel.sink.add('your message'). When finished, close the connection cleanly using channel.sink.close(status.goingAway), importing the standard codes from the status.dart library.