Introducción

WebSocket es un protocolo que permite conexiones persistentes full-duplex entre cliente y servidor sobre un único socket TCP. A diferencia del HTTP plano, donde el cliente debe solicitar y el servidor responde, una conexión WebSocket permanece abierta y ambos lados pueden enviar mensajes en cualquier momento. Esto lo hace perfecto para aplicaciones de chat, dashboards en vivo, juegos multijugador y cualquier función que necesite actualizaciones en tiempo real.

En esta lección construirás la configuración WebSocket más pequeña posible: un servidor en Node.js usando la popular biblioteca `ws`, y un cliente de navegador que se conecta a él e intercambia algunos mensajes. Sin frameworks, sin bases de datos — solo el protocolo en bruto para que entiendas qué está sucediendo bajo el capó.

Configurando el proyecto

Crea una nueva carpeta para el proyecto e inicialízala. Necesitas tener Node.js instalado (la versión 18 o posterior está bien).

mkdir ws-demo
cd ws-demo
npm init -y
npm install ws

El paquete `ws` es una implementación de WebSocket rápida y ampliamente utilizada para Node.js. Después de `npm install`, tendrás una carpeta `node_modules` y un `package.json` que lista `ws` como dependencia.

Escribiendo el servidor

Crea un archivo llamado `server.js`. El servidor hace tres cosas: importar la biblioteca, crear un servidor WebSocket vinculado a un puerto y definir qué sucede en la conexión y en los mensajes entrantes.

const WebSocket = require('ws');

const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', (ws) => {
  console.log('A client connected');

  ws.on('message', (data) => {
    const text = data.toString();
    console.log('Received:', text);
    ws.send(`Server echo: ${text}`);
  });

  ws.send('Welcome to the WebSocket server!');
});

console.log('WebSocket server is listening on ws://localhost:8080');

El evento `connection` se dispara una vez por cada cliente que se conecta. La callback recibe un objeto `ws` que representa el socket de ese cliente individual. Dentro de la callback adjuntas un listener de `message`. Cuando llega un mensaje, `data` es un Buffer por defecto, por lo que `toString()` lo convierte a texto plano. El servidor luego hace eco del mensaje de vuelta anteponiendo `Server echo:`.

Ejecuta el servidor con `node server.js`. Deberías ver la línea de log "listening" y nada más hasta que un cliente se conecte.

Escribiendo el cliente del navegador

Crea un archivo llamado `index.html`. Un navegador puede abrir una conexión WebSocket usando el global `WebSocket` incorporado — no se necesita ninguna biblioteca en el lado del cliente.

<!DOCTYPE html>
<html>
<head><title>WebSocket Demo</title></head>
<body>
  <h1>WebSocket Demo</h1>
  <input id="msg" placeholder="Type a message" />
  <button id="send">Send</button>
  <ul id="log"></ul>

  <script>
    const log = document.getElementById('log');
    const ws = new WebSocket('ws://localhost:8080');

    ws.addEventListener('open', () => {
      log.innerHTML += '<li>Connected to server</li>';
    });

    ws.addEventListener('message', (event) => {
      log.innerHTML += '<li>From server: ' + event.data + '</li>';
    });

    document.getElementById('send').addEventListener('click', () => {
      const input = document.getElementById('msg');
      ws.send(input.value);
      input.value = '';
    });
  </script>
</body>
</html>

El evento `open` se dispara cuando se completa el handshake. Después de eso, `ws.send('text')` envía un mensaje de texto al servidor. La respuesta eco del servidor llega como un evento `message` cuyo `event.data` es la cadena que el servidor envió.

Probándolo de extremo a extremo

Inicia el servidor con `node server.js`. Luego abre `index.html` en tu navegador (puedes hacer doble clic, o usar una herramienta como `npx serve`). En la terminal deberías ver "A client connected" en el momento en que se carga la página. Escribe algo en el cuadro de entrada y haz clic en Send. El log del navegador mostrará tu mensaje con el prefijo `Server echo:`, y la terminal registrará cada mensaje que el servidor recibe.

Errores comunes

Olvidar `data.toString()` en el lado del servidor te da un objeto Buffer crudo en lugar de la cadena legible que envió el cliente. Olvidar el prefijo del protocolo `ws://` en la URL del navegador lanzará un error de sintaxis porque el constructor `WebSocket` requiere la URL completa incluyendo el esquema. Si el servidor no está en ejecución, el evento `open` del navegador nunca se disparará y no verás ninguna entrada de log — siempre revisa primero la terminal cuando no pase nada.

Resumen

Ahora tienes un servidor de eco WebSocket funcional y un cliente de navegador. El servidor usa `ws` para escuchar en el puerto 8080, acepta conexiones y hace eco de cualquier mensaje que reciba. El cliente abre la conexión con `new WebSocket('ws://localhost:8080')` y usa los eventos `send` y `message` para comunicarse. Este patrón — un servidor, muchos clientes conectados, mensajes bidireccionales — es la base sobre la que se construye cualquier función en tiempo real.