> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wsx.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Quick Start
> Get WSX running in under 5 minutes
## 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:
```bash Express theme={null}
npm install @wsx-sh/core @wsx-sh/express
```
```bash Hono theme={null}
npm install @wsx-sh/core @wsx-sh/hono
```
## Step 2: Create Your Server
```javascript Express theme={null}
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(`
WSX Quick Start
WSX Counter
Count: ${counter}
`);
});
// 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}`);
});
```
```javascript Hono theme={null}
import { createHonoWSXServer } from "@wsx-sh/hono";
// Create WSX server
const wsx = createHonoWSXServer();
const app = wsx.getApp();
// Global counter
let counter = 0;
// Serve HTML page
app.get("/", (c) => {
return c.html(`
WSX Quick Start
WSX Counter
Count: ${counter}
`);
});
// 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}`,
};
});
export default {
fetch: app.fetch,
};
```
## Step 3: Add the Client Library
Copy the WSX client library to your public directory:
```bash theme={null}
cp node_modules/@wsx-sh/client/wsx.js public/wsx.js
```
Or download it from the [GitHub repository](https://github.com/stukennedy/wsx/blob/main/packages/client/wsx.js).
## Step 4: Run Your Application
```bash Express theme={null}
node server.js
```
```bash Hono theme={null}
npm run dev
```
## 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.
```ts theme={null}
// 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)`);
});
```
```js theme={null}
// 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:
Learn about throttling, debouncing, and conditional triggers
Update multiple DOM elements from a single response
Build real-time forms with validation and submission
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:
* [Real-time Chat Application](/examples/chat)
* [Live Search with Debouncing](/examples/live-search)
* [Dashboard with Broadcasting](/examples/dashboard)