Skip to main content

​
Overview

This quick start guide will get you up and running with WSX in under 5 minutes. We’ll build a simple real-time counter that updates across all connected clients.

​
Prerequisites

  • Node.js 18 or later
  • npm or yarn

​
Step 1: Install WSX

Choose your framework and install the corresponding packages: 
npm install @wsx-sh/core @wsx-sh/express

​
Step 2: Create Your Server

import { createExpressWSXServer } from "@wsx-sh/express";
import express from "express";
import path from "path";
import { fileURLToPath } from "url";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

// Create WSX server
const wsx = createExpressWSXServer();
const app = wsx.getApp();

// Global counter
let counter = 0;

// Serve static files
app.use(express.static(path.join(__dirname, "public")));

// Serve HTML page
app.get("/", (req, res) => {
  res.send(`
    <!DOCTYPE html>
    <html>
    <head>
      <title>WSX Quick Start</title>
      <script src="https://cdn.tailwindcss.com"></script>
      <script src="/wsx.js"></script>
    </head>
    <body class="bg-gray-100 p-8">
      <div wx-config='{"url": "ws://localhost:3000/ws", "debug": true}'>
        <h1 class="text-2xl font-bold mb-4">WSX Counter</h1>
        <div id="counter" class="text-xl mb-4">Count: ${counter}</div>
        <button 
          wx-send="increment" 
          wx-target="#counter"
          class="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600"
        >
          Increment
        </button>
      </div>
    </body>
    </html>
  `);
});

// Handle increment events
wsx.on("increment", async (request, connection) => {
  counter++;

  // Broadcast to all connected clients
  wsx.broadcast("#counter", `Count: ${counter}`);

  return {
    id: request.id,
    target: request.target,
    html: `Count: ${counter}`,
  };
});

// Start server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

​
Step 3: Add the Client Library

Copy the WSX client library to your public directory: 
cp node_modules/@wsx-sh/client/wsx.js public/wsx.js
Or download it from the GitHub repository.

​
Step 4: Run Your Application

node server.js

​
Step 5: Test It Out

  1. Open your browser to http://localhost:3000 (or http://localhost:8787 for Hono)
  2. Click the “Increment” button
  3. Open another browser tab/window to the same URL
  4. Click the button in either tab - both will update in real-time!

​
What Just Happened?

Let’s break down what we built:

​
HTML Attributes

  • wx-config: Configures the WebSocket connection
  • wx-send: Defines the handler name to call on the server
  • wx-target: Specifies which element to update with the response

​
Server Handler

The wsx.on("increment", ...) handler:
  1. Increments the counter
  2. Broadcasts the update to all connected clients
  3. Returns a response for the triggering client

​
Real-time Updates

When you click the button:
  1. WSX sends a WebSocket message to the server
  2. The server processes the request and updates the counter
  3. The server broadcasts the new count to all connected clients
  4. All browser windows update simultaneously

​
JSON & Binary Messaging

HTML swaps are just one of the delivery mechanisms WSX supports. You can also stream binary data or publish JSON payloads to named channels. 
// Add alongside your existing handlers
wsx.onJson("presence", async (message, connection) => {
  wsx.broadcastJson("presence", {
    userId: connection.id,
    status: message.data.status,
  });
});

wsx.onStream("audio", async (message, chunk) => {
  console.log(`Audio frame ${message.id} (${chunk.byteLength} bytes)`);
});

// Client-side helpers
wsx.onJson("presence", ({ data }) => {
  console.log("Presence", data);
});

wsx.sendJson("presence", { status: "online" });

await wsx.sendStream("audio", microphoneChunk, {
  metadata: { mimeType: microphoneChunk.type },
});
See the server and client guides for deeper coverage of JSON channels and binary streams.

​
Next Steps

Now that you have WSX running, explore these features:

Advanced Triggers

Learn about throttling, debouncing, and conditional triggers

Out-of-Band Updates

Update multiple DOM elements from a single response

Form Handling

Build real-time forms with validation and submission

Broadcasting

Send targeted updates to specific clients or groups

​
Common Issues

Make sure your WebSocket URL in wx-config matches your server configuration. Check the browser console for connection errors.
Ensure the WSX client library is loaded before the page content. Check that the wx-send attribute is set correctly.
Verify that your server handler is calling wsx.broadcast() to update all connected clients, not just returning a response.

​
Ready for More?

Check out our comprehensive examples: