​
Package Overview

WSX is organized as a monorepo with separate packages for different use cases:
  • @wsx-sh/core: Core WSX server functionality (required)
  • @wsx-sh/express: Express.js adapter
  • @wsx-sh/hono: Hono framework adapter
  • @wsx-sh/client: Client-side JavaScript library

​
Prerequisites

  • Node.js 18 or later
  • npm, yarn, or pnpm

​
Server Installation

​
Express.js

For Express.js applications: 
npm install @wsx-sh/core @wsx-sh/express

​
Hono

For Hono applications (including Cloudflare Workers): 
npm install @wsx-sh/core @wsx-sh/hono

​
Core Only

If you want to create a custom adapter: 
npm install @wsx-sh/core

​
Client Installation

​
Option 1: Download from Repository

Download the client library from the GitHub repository and include it in your HTML: 
<script src="/path/to/wsx.js"></script>

​
Option 2: Copy from node_modules

If you’ve installed the server packages, you can copy the client from node_modules: 
cp node_modules/@wsx-sh/client/wsx.js public/wsx.js

​
Option 3: CDN (Coming Soon)

We’re working on CDN distribution. For now, use the download or copy methods above.

​
TypeScript Support

WSX is written in TypeScript and includes full type definitions. No additional @types packages are needed. 
import { WSXServer, WSXRequest, WSXResponse } from "@wsx-sh/core";
import { createExpressWSXServer } from "@wsx-sh/express";

const wsx = createExpressWSXServer();

wsx.on("my-handler", async (request: WSXRequest, connection) => {
  const response: WSXResponse = {
    id: request.id,
    target: request.target,
    html: "<div>Hello TypeScript!</div>",
  };
  return response;
});

​
Framework-Specific Setup

​
Express.js

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

const wsx = createExpressWSXServer();
const app = wsx.getApp();

// Your Express middleware and routes
app.use(express.static("public"));

// WSX handlers
wsx.on("my-handler", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: "<div>Hello from Express!</div>",
  };
});

const server = app.listen(3000, () => {
  console.log("Server running on port 3000");
});

​
Hono

import { createHonoWSXServer } from "@wsx-sh/hono";

const wsx = createHonoWSXServer();
const app = wsx.getApp();

// Your Hono routes
app.get("/", (c) => c.html("<h1>Hello Hono!</h1>"));

// WSX handlers
wsx.on("my-handler", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: "<div>Hello from Hono!</div>",
  };
});

export default {
  fetch: app.fetch,
};

​
Cloudflare Workers

WSX works great with Cloudflare Workers using the Hono adapter: 
import { createHonoWSXServer } from "@wsx-sh/hono";

const wsx = createHonoWSXServer();
const app = wsx.getApp();

// Your worker logic
wsx.on("worker-handler", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: "<div>Hello from Cloudflare Workers!</div>",
  };
});

export default {
  fetch: app.fetch,
};

​
Verification

To verify your installation is working:
  1. Server: Check that you can import and create a WSX server:
import { createExpressWSXServer } from "@wsx-sh/express";
const wsx = createExpressWSXServer();
console.log("WSX server created successfully");
  1. Client: Check that the client library loads without errors:
<script src="/wsx.js"></script>
<script>
  console.log("WSX client loaded:", typeof WSX !== "undefined");
</script>

​
Common Issues

​
Development vs Production

​
Development

For development, you can use the debug mode: 
<div wx-config='{"url": "ws://localhost:3000/ws", "debug": true}'>
  <!-- Your content -->
</div>

​
Production

For production, disable debug mode and use secure WebSocket connections: 
<div wx-config='{"url": "wss://your-domain.com/ws", "debug": false}'>
  <!-- Your content -->
</div>

​
Next Steps

Now that you have WSX installed, check out:

Quick Start

Build your first WSX application

Architecture

Understand how WSX works

Examples

Explore real-world examples

API Reference

Detailed API documentation