Skip to main content

​
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

Make sure you’ve installed the correct packages for your framework: - Express: @wsx-sh/core and @wsx-sh/express - Hono: @wsx-sh/core and @wsx-sh/hono
  • Custom: @wsx-sh/core only
Ensure your TypeScript configuration includes the node_modules directory and that you’re using TypeScript 4.5 or later.
Verify that the wsx.js file is in your public directory and accessible via HTTP. Check your server’s static file serving configuration.
If you’re using a reverse proxy (nginx, Apache), make sure it’s configured to handle WebSocket upgrades. See our deployment guide for details.

​
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