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:

Hono

For Hono applications (including Cloudflare Workers):

Core Only

If you want to create a custom adapter:

Client Installation

Option 1: Download from Repository

Download the client library from the GitHub repository and include it in your HTML:

Option 2: Copy from node_modules

If you’ve installed the server packages, you can copy the client from node_modules:

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.

Framework-Specific Setup

Express.js

Hono

Cloudflare Workers

WSX works great with Cloudflare Workers using the Hono adapter:

Verification

To verify your installation is working:
  1. Server: Check that you can import and create a WSX server:
  1. Client: Check that the client library loads without errors:

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:

Production

For production, disable debug mode and use secure WebSocket connections:

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