DEV Community: Jérôme

sioxx — a modern C++ socket.io client (nlohmann/json + Boost.Beast, JSON or MessagePack)

Jérôme — Tue, 14 Jul 2026 19:57:13 +0000

If you've ever tried to use socket.io-client-cpp in a project built in the last few years, you know the friction: it vendors RapidJSON, it vendors websocketpp, its CMake predates target_link_libraries being cool, and pulling it into a project that already depends on nlohmann/json and Boost.Asio means either forking it or living with two JSON libraries in your binary.

I needed a socket.io client for a system with existing nlohmann::json and Boost.Beast dependencies, so instead of fighting the old library I rewrote it. The result is sioxx — same job, different guts:

🔗 github.com/jfayot/sioxx

What changed vs. the original

	`socket.io-client-cpp`	`sioxx`
JSON	RapidJSON	nlohmann/json
WebSocket	websocketpp	Boost.Beast (`boost::asio` + `boost::beast::websocket`)
Wire protocol	JSON only	JSON or MessagePack, selectable per client
Transport	WebSocket	WebSocket first, HTTP long-polling fallback
Reconnection	basic retry	capped exponential backoff with jitter
Build	vendored deps, older CMake	modern CMake + CPM.cmake, `find_package`, full `install(EXPORT ...)`
Tests	Catch2 tests	GoogleTest suite (parsers, transports, URL parsing, reconnection, socket bookkeeping, engine.io framing)

The public API keeps the same shape you'd expect from socket.io — client, socket("/namespace"), on(event, handler), emit(event, data), ack callbacks — but almost everything under the hood is new.

The JSON value problem, solved by not solving it

The original library has a whole sio::message class hierarchy — int_message, string_message, object_message, array_message, binary_message — basically reimplementing a JSON value type from scratch. But nlohmann::json is a JSON value type, and it already handles null/bool/int/double/string/array/object and raw binary via json::binary_t. So sioxx::message is just:

namespace sioxx {
  using json = nlohmann::json;
  using message = json;          // that's it
  using message_list = json;     // always a JSON array
}

That one decision deletes an entire subsystem. Building event args is just building a json array:

sock->emit("hello", sioxx::json{"world"});
sock->emit("ping_ack", sioxx::json::array({1, 2, 3}), [](sioxx::message reply) {
  std::cout << "ack: " << reply.dump() << "\n";
});

Two wire protocols behind one interface

socket.io actually has two parsers in the wild: the default text protocol, and socket.io-msgpack-parser for binary-heavy workloads. sioxx models this as a small strategy interface:

class parser_base {
public:
  virtual void encode(const socketio_packet& packet, const frame_writer& write) const = 0;
  virtual bool decode(const std::string& payload, bool is_binary, socketio_packet& out) const = 0;
  virtual std::string name() const = 0;
};

json_parser implements the classic <type><nsp>,<id><json> text framing (2["chat message","hi"], 2/chat,3["ack me"], …).

msgpack_parser is more interesting: instead of pulling in a separate MessagePack library, it's built entirely on nlohmann::json::to_msgpack / from_msgpack. Each packet becomes one MessagePack-encoded map (with optional id and data fields):

void msgpack_parser::encode(const socketio_packet& packet, const frame_writer& write) const {
  json obj = { {"type", (int)packet.type}, {"nsp", packet.nsp} };
  if (packet.id >= 0) obj["id"] = packet.id;
  if (!packet.data.is_null()) obj["data"] = packet.data;
  auto bytes = json::to_msgpack(obj);
  write(std::string(reinterpret_cast<const char*>(bytes.data()), bytes.size()), /*is_binary=*/true);
}

The nice side effect: because json::binary_t maps straight onto MessagePack's bin type, binary payloads round-trip natively through the msgpack parser — no placeholder/reconstruction dance needed for BINARY_EVENT/BINARY_ACK, which the JSON protocol normally requires. Pick your parser with one field:

sioxx::client_options opts;
opts.parser = sioxx::parser_kind::msgpack;   // or parser_kind::json (default)
sioxx::client client(opts);

Boost.Beast instead of websocketpp

websocket_transport owns its own boost::asio::io_context on a background thread, supports both ws:// and wss:// (TLS via OpenSSL, SNI included), and serializes writes through a small queue since Beast streams can't be written to concurrently:

class websocket_transport final : public transport_base,
                                   public std::enable_shared_from_this<websocket_transport> {
public:
  void connect(const std::string& url) override;
  void send(const std::string& payload, bool is_binary) override;
  void close() override;
  // ...
};

transport_base is a tiny abstract interface: engine.io only knows how to open, send, close, and receive opaque frames. That made it possible to add a second concrete transport without changing the protocol layers above it.

HTTP long-polling when WebSocket is unavailable

WebSocket is still the preferred path, but sioxx now falls back to Engine.IO v4 HTTP long-polling if the initial WebSocket connection fails. The polling transport performs the normal Engine.IO GET/POST cycle, opens a fresh HTTP(S) connection for each poll or write, honors the same TLS and extra-header settings, and encodes binary polling frames as Engine.IO b + base64 packets.

The fallback is visible through the existing error listener:

[sioxx] error: WebSocket connection failed; switching to HTTP long-polling

You can also force polling from the start, which is useful for environments that block WebSocket upgrades and for testing:

sioxx::client_options opts;
opts.force_http_polling = true;
sioxx::client client(opts);

Layering: engine.io → socket.io → namespaces

The stack mirrors the real socket.io/engine.io split:

sioxx::client
  └─ socketio_client_impl        (packet dispatch, namespace registry)
       └─ engineio_client         (engine.io v4 handshake, ping/pong heartbeat)
            └─ websocket_transport (Boost.Beast ws/wss)
               or http_polling_transport (Engine.IO HTTP(S) polling)

engineio_client does the OPEN handshake, tracks pingInterval/pingTimeout from the server, and runs a heartbeat thread that closes the connection if pongs stop arriving. socketio_client_impl decodes packets with whichever parser_base you picked and routes EVENT/ACK/CONNECT/DISCONNECT packets to the right socketio_socket by namespace:

auto sock = client.socket("/your_namespace");

sock->on("your_message", [](const std::string& event, sioxx::message data) {
    // data is a nlohmann::json array of the event's arguments
});

client.connect("wss://example.com");

Modern CMake, actually modern

This was half the point of the rewrite. CMakeLists.txt does what you'd expect from a modern C++ library:

nlohmann/json and Boost via CPM.cmake (or -DSIOXX_USE_SYSTEM_JSON=ON to use an installed nlohmann/json)
OpenSSL and Threads via find_package
a proper install(EXPORT sioxxTargets ...) + generated sioxxConfig.cmake, so downstream projects just do:

find_package(sioxx REQUIRED)
target_link_libraries(my_app PRIVATE sioxx::sioxx)

No manual include paths, no copy-pasting source files into your project.

The CMake switches are deliberately small: SIOXX_BUILD_EXAMPLES,
SIOXX_BUILD_TESTS, and SIOXX_USE_SYSTEM_JSON. The library requires CMake
3.20+ and a C++17 compiler.

Connection options and threading

client_options also exposes TLS verification and extra HTTP/WebSocket
upgrade headers, so development servers with self-signed certificates and
cookie/token-based deployments do not require a transport fork:

sioxx::client_options opts;
opts.verify_tls = false;  // development/self-signed certificates only
opts.extra_headers = {{"Authorization", "Bearer example-token"}};

The transport runs its Asio work on a background thread. Event listeners,
ack callbacks, and open/close/error callbacks therefore run on that thread;
applications with a UI or another thread-affine runtime should dispatch work
back to their own queue.

Tests

There's a GoogleTest suite (also fetched through CPM.cmake) covering the parts that don't need a live server:

parser round-trips — JSON and MessagePack encode/decode, namespaces, ack ids, malformed input, binary attachments
socketio_socket bookkeeping — on/off/emit/ack callbacks, tested with an empty weak_ptr<socketio_client_impl> so no network is involved at all
engineio_client framing — handshake, ping→pong, message prefixing, binary passthrough — tested against a small in-memory fake transport_base instead of a real socket
polling framing — binary base64 packet encoding/decoding used by the HTTP polling transport
URL parsing — ws/wss scheme, host, ports, paths, and invalid URLs
reconnection policy — deterministic exponential growth, maximum-delay capping, and jitter bounds

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DSIOXX_BUILD_TESTS=ON
cmake --build build -j
ctest --test-dir build --output-on-failure

The actual network transports are exercised end-to-end by the example client against the bundled Socket.IO server.

Reconnection that backs off instead of stampeding

Reconnects are configurable per client. Each attempt doubles the delay up to a cap, then applies symmetric jitter. The default is a 2-second initial delay, a 30-second cap, and a randomization factor of 0.5. Set attempts to zero to disable reconnection.

sioxx::client_options opts;
opts.reconnect_attempts = 5;
opts.reconnect_delay = std::chrono::milliseconds(1000);
opts.reconnect_delay_max = std::chrono::milliseconds(30000);
opts.reconnect_randomization_factor = 0.5;

Try it

sudo apt install libssl-dev cmake
git clone https://github.com/jfayot/sioxx
cmake -S sioxx -B sioxx/build -DCMAKE_BUILD_TYPE=Release
cmake --build sioxx/build -j
./sioxx/build/sioxx_basic_client

The repository also includes examples/test_server, a minimal Node.js Socket.IO server that mirrors the example namespace and events. It supports JSON or MessagePack and WebSocket+polling or polling-only modes:

cd sioxx/examples/test_server
pnpm install
pnpm start                       # JSON, WebSocket + polling
# or: pnpm start:msgpack
# or: pnpm start:polling          # JSON, polling only
# or: pnpm start:msgpack-polling

# From the repository root:
./build/sioxx_basic_client polling
./build/sioxx_basic_client msgpack polling

The server logs the active transport, so a polling test visibly reports (polling) on connect.

GitHub Actions builds and tests the project on Ubuntu, macOS, and Windows with GCC, Clang, and MSVC. Pushing a v* tag runs that matrix and, after it succeeds, creates a GitHub Release with generated notes.

What's still missing

Being upfront about the gaps:

The JSON parser recognizes BINARY_EVENT/BINARY_ACK headers but doesn't implement the placeholder reconstruction for multi-attachment binary payloads — use the MessagePack parser for binary data.
Long-polling is a fallback (or an explicitly forced mode); sioxx does not upgrade an established polling session back to WebSocket.

If any of that matters for your use case, PRs welcome: github.com/jfayot/sioxx

Zero-config Cesium.js in Vite — introducing vite-plugin-cesium-engine

Jérôme — Tue, 24 Mar 2026 21:15:04 +0000

If you've ever tried to use CesiumJS with Vite, you know the ritual. Before you can render a globe you have to:

Copy WASM workers and assets to your output directory
Set window.CESIUM_BASE_URL before any Cesium module loads
Inject a <link> tag for CesiumWidget.css
Somehow get your Ion access token into the bundle

Every project starts the same way: copy-paste from a StackOverflow answer, tweak until it works in dev, discover it breaks in prod, repeat.

I built vite-plugin-cesium-engine to make all of that disappear.

What it targets

There are already a couple of Cesium Vite plugins out there, but they all target the full cesium package — the one that comes with the entire Viewer UI. If you want the lean @cesium/engine core (no widgets, full control over your own UI), you were on your own.

This plugin is purpose-built for @cesium/engine only.

Installation

# npm
npm i -D @cesium/engine vite-plugin-cesium-engine

# pnpm
pnpm add -D @cesium/engine vite-plugin-cesium-engine

# yarn
yarn add -D @cesium/engine vite-plugin-cesium-engine

Basic usage

Add it to your Vite config:

// vite.config.ts
import { defineConfig } from "vite";
import { cesiumEngine } from "vite-plugin-cesium-engine";

export default defineConfig({
  plugins: [cesiumEngine()],
});

That's the entire setup. No CESIUM_BASE_URL, no asset copy scripts, no CSS imports. Then use Cesium directly:

import { CesiumWidget, Terrain } from "@cesium/engine";

const widget = new CesiumWidget(document.getElementById("app")!, {
  terrain: Terrain.fromWorldTerrain(),
});

The plugin automatically:

Copies WASM workers, built files, and CesiumWidget.css to your output directory
Injects window.CESIUM_BASE_URL into your HTML before any module loads
Injects the CesiumWidget.css <link> tag
Serves assets directly from node_modules during vite dev (no copying needed)

Framework examples

The setup is identical across frameworks — only the lifecycle hooks differ.

React

// src/main.tsx
import { useEffect, useRef } from "react";
import { CesiumWidget, Terrain } from "@cesium/engine";

export default function App() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!containerRef.current) return;
    const widget = new CesiumWidget(containerRef.current, {
      terrain: Terrain.fromWorldTerrain(),
    });
    return () => widget.destroy();
  }, []);

  return <div ref={containerRef} style={{ width: "100%", height: "100vh" }} />;
}

Vue

<script setup lang="ts">
import { ref, onMounted, onBeforeUnmount } from "vue";
import { CesiumWidget, Terrain } from "@cesium/engine";

const container = ref<HTMLDivElement>();
let widget: CesiumWidget;

onMounted(() => {
  widget = new CesiumWidget(container.value!, {
    terrain: Terrain.fromWorldTerrain(),
  });
});

onBeforeUnmount(() => widget?.destroy());
</script>

<template>
  <div ref="container" style="width: 100%; height: 100%" />
</template>

Svelte

<script lang="ts">
  import { onMount } from "svelte";
  import { CesiumWidget, Terrain } from "@cesium/engine";

  let container: HTMLDivElement;

  onMount(() => {
    const widget = new CesiumWidget(container, {
      terrain: Terrain.fromWorldTerrain(),
    });
    return () => widget.destroy();
  });
</script>

<div bind:this={container} style="width: 100%; height: 100%" />

Vanilla TypeScript

// src/main.ts
import { CesiumWidget, Terrain } from "@cesium/engine";

const widget = new CesiumWidget(document.getElementById("app")!, {
  terrain: Terrain.fromWorldTerrain(),
});

if (import.meta.hot) {
  import.meta.hot.dispose(() => widget.destroy());
}

Complete, ready-to-run starter projects for all four frameworks are available in the examples/ directory of the repository.

Ion token — baked in at build time

Set your Cesium Ion access token through the plugin options and it gets injected at build time — no Ion.defaultAccessToken = ... in your app code, no runtime env variable reading:

cesiumEngine({
  ionToken: process.env.CESIUM_ION_TOKEN,
})

Per-environment tokens

Pass a { [mode]: token } map to use different tokens per Vite mode:

cesiumEngine({
  ionToken: {
    development: process.env.CESIUM_ION_TOKEN_DEV,
    production:  process.env.CESIUM_ION_TOKEN_PROD,
  },
})

vite dev    # injects CESIUM_ION_TOKEN_DEV
vite build  # injects CESIUM_ION_TOKEN_PROD

The plugin also validates that the token looks like a valid JWT at startup and warns you if it doesn't — catching .env substitution failures before they become runtime surprises.

Virtual module — typed runtime constants

The plugin exposes a virtual:cesium module so your app code can read CESIUM_BASE_URL and ION_TOKEN without touching window globals:

// tsconfig.json
{
  "compilerOptions": {
    "types": ["vite-plugin-cesium-engine/virtual"]
  }
}

import { CESIUM_BASE_URL, ION_TOKEN } from "virtual:cesium";

console.log(CESIUM_BASE_URL); // "/cesium/"
console.log(ION_TOKEN);       // your token, or null

Both values are resolved at build time and tree-shaken if unused.

Custom asset paths

For CDN deployments or frameworks with opinionated public directories (Laravel, Rails, etc.), you can control exactly where assets land and where they're served from:

// vite.config.ts
export default defineConfig({
  base: "/app/",
  plugins: [
    cesiumEngine({
      assetsPath: "vendor/cesium",        // dist/vendor/cesium/
      cesiumBaseUrl: "/app/vendor/cesium", // served from here
    }),
  ],
});

The plugin warns at startup if cesiumBaseUrl doesn't start with Vite's base, so misconfigurations are caught immediately rather than at runtime in production.

Debug mode

If something isn't wiring up as expected, debug: true prints a full summary at dev-server startup:

cesiumEngine({ debug: true })

[cesium-engine] mode         : development
[cesium-engine] vite base    : ""
[cesium-engine] cesiumBaseUrl: "/cesium"
[cesium-engine] assetsPath   : "cesium"
[cesium-engine] ionToken     : eyJhbGciOiJ… (mode: development)
[cesium-engine] copying assets:
  ThirdParty/*.wasm → cesium/ThirdParty
  Build/*           → cesium
  Source/Assets/    → cesium
  Widget/*.css      → cesium/Widget

Known warning: protobufjs eval

You may see this Rollup warning in your build output:

[EVAL] Use of direct eval function is strongly discouraged
  node_modules/protobufjs/dist/minimal/protobuf.js

This comes from protobufjs, a transitive dependency of @cesium/engine. The eval is intentional in that library and not a security issue. Suppress it in your vite.config.ts:

build: {
  rollupOptions: {
    onwarn(warning, defaultHandler) {
      if (warning.code === "EVAL" && warning.id?.includes("protobufjs")) return;
      defaultHandler(warning);
    },
  },
},

Zero runtime dependencies

The plugin has no runtime dependencies — it uses only Node built-ins (node:fs, node:path) and Vite's own plugin API. What gets installed alongside it is exactly nothing beyond what you already have.