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

Updated in August 2026: this article reflects sioxx v0.2.0 and the latest additions on main, including binary attachments with the default JSON parser.

The established socket.io-client-cpp remains a useful C++ Socket.IO client. Its architecture, however, is built around websocketpp, standalone Asio, a custom sio::message hierarchy, and RapidJSON for serialization. Its dependencies are provided as Git submodules by default, although current versions can also use installed packages and provide modern CMake targets.

The networking dependency is also showing its age. websocketpp last received a commit on 19 April 2025, roughly 16 months ago at the time of this update. Its two commits in 2025 were a single maintenance change to support CMake 4; before that, the previous commit was in April 2020. In practice, functional development has been dormant for more than six years.

I needed a client that fitted applications already using Boost.Asio, Boost.Beast, and nlohmann::json, without adding a second networking and JSON stack. That led to sioxx: a C++17 Socket.IO client with a familiar event-driven API, but a different implementation.

🔗 GitHub: jfayot/sioxx
🔗 Documentation: Read the docs

How sioxx differs

	`socket.io-client-cpp`	`sioxx`
Payload model	custom `sio::message` types; RapidJSON serialization	`nlohmann::json` aliases
Networking	standalone Asio + websocketpp	Boost.Asio + Boost.Beast
Socket.IO parsers	default JSON protocol	JSON, MessagePack, or an application-defined parser
Engine.IO transports	WebSocket	WebSocket with HTTP long-polling fallback, or forced polling
Reconnection	capped exponential backoff	capped exponential backoff with configurable symmetric jitter
Build and packaging	submodules by default or installed dependencies; CMake install/export	`FetchContent` by default or system Boost/JSON; CMake install/export and Conan 2 recipe
Tests	Catch2 packet tests	GoogleTest unit tests plus opt-in Node.js-backed end-to-end tests

The API deliberately retains the shape expected from a Socket.IO client — client, socket("/namespace"), on(), emit(), and acknowledgements — but it is not intended to be a drop-in replacement. The documentation includes a practical migration guide.

Use nlohmann/json directly

The original client defines a hierarchy of message types. sioxx instead uses nlohmann::json as its public value type:

namespace sioxx {
  using json = nlohmann::json;
  using message = json;
  using message_list = json; // an array of event arguments
}

Event arguments therefore use ordinary JSON values:

auto socket = client.socket("/chat");

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

sioxx::binary_message() creates a json::binary_t value from a byte buffer, so binary data uses the same message API as strings, numbers, arrays, and objects with either built-in parser.

Built-in JSON and MessagePack parsers

Socket.IO uses a parser above the Engine.IO transport. sioxx ships with two parser strategies:

json_parser implements the standard Socket.IO text protocol.
msgpack_parser implements socket.io-msgpack-parser using nlohmann::json::to_msgpack() and from_msgpack(), with no additional MessagePack dependency.

The parser is selected per client and must match the server configuration:

sioxx::client_options options;
options.parser = sioxx::parser_kind::msgpack; // JSON is the default
sioxx::client client(options);

Applications can also provide a parser_factory. The repository demonstrates this with a CBOR parser and a matching Node.js server. Parser negotiation is intentionally not automatic, just as it is not automatic in the JavaScript clients.

Binary attachments with either parser

Both built-in parsers support binary values, including multiple or nested json::binary_t values in events and acknowledgements.

The default JSON parser implements Socket.IO's BINARY_EVENT and BINARY_ACK placeholder protocol for both encoding and decoding. It sends binary values as attachment frames and reconstructs the original JSON structure once all attachments arrive. Polling writes are serialized so the header and its attachments remain in wire order.

The same value works with either built-in parser:

auto bytes = sioxx::binary_message(
  std::vector<std::uint8_t>{0x00, 0x7f, 0xff});

socket->emit("upload", sioxx::make_args(bytes));

MessagePack carries the value in one binary frame, while the JSON parser uses the standard placeholder plus attachment frames.

WebSocket and HTTP long-polling

WebSocket is the preferred transport. If the initial WebSocket connection fails, sioxx can fall back to Engine.IO v4 HTTP long-polling. Polling may also be selected from the start:

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

The polling implementation performs the Engine.IO GET/POST cycle over HTTP or HTTPS, supports extra headers and TLS verification settings, and uses Engine.IO base64 framing when a polling packet contains binary data. Each poll or write currently opens a fresh HTTP connection, and an established polling session is not upgraded back to WebSocket.

Layers and threading

The implementation follows the Socket.IO/Engine.IO split:

sioxx::client
  └─ client_impl                   Socket.IO packets and namespace registry
       └─ engineio_client          Engine.IO v4 handshake and heartbeat
            ├─ websocket_transport     Boost.Beast WebSocket (ws/wss)
            └─ http_polling_transport  HTTP(S) long-polling

engineio_client reads pingInterval and pingTimeout from the Engine.IO handshake, responds to server pings with pongs, and detects heartbeat timeouts. The selected parser decodes Socket.IO packets, while client_impl routes events and acknowledgements to the correct namespace socket.

Networking runs on background threads. Event handlers, acknowledgement callbacks, and lifecycle/error listeners therefore also run there. A GUI or any other thread-affine application must dispatch work back to its own thread. The optional Qt Widgets chat example shows that pattern.

Namespaces, authentication, buffering, and acknowledgements

The v0.2.0 API supports namespace authentication, custom Engine.IO paths and query parameters, catch-all listeners, and acknowledgements in both directions:

sioxx::client_options options;
options.engineio_path = "/io/";
options.query = {{"client", "desktop"}};
options.extra_headers = {{"Authorization", "Bearer example-token"}};
options.reconnect_attempts = 5;

sioxx::client client(options);
auto socket = client.socket("/chat", {{"token", "namespace-token"}});

socket->on(
  "question",
  [](const std::string&, sioxx::message data,
     sioxx::socket::ack_callback acknowledge) {
    acknowledge(sioxx::make_args("received"));
  });

socket->on_any([](const std::string& event, sioxx::message data) {
  std::cout << event << ": " << data.dump() << "\n";
});

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

Events emitted before a namespace finishes connecting are buffered per namespace and flushed in order, including events that request acknowledgements.

Reconnection

Reconnects use capped exponential backoff. sioxx doubles the delay for each attempt and can apply symmetric jitter to reduce synchronized reconnect storms:

sioxx::client_options options;
options.reconnect_attempts = 5; // zero disables reconnection
options.reconnect_delay = std::chrono::milliseconds(1000);
options.reconnect_delay_max = std::chrono::milliseconds(30000);
options.reconnect_randomization_factor = 0.5;

CMake and packaging

sioxx currently requires CMake 3.28, a C++17 compiler, Boost 1.74 or newer, nlohmann-json 3.8 or newer, and OpenSSL. By default, CMake fetches tested Boost and JSON versions with FetchContent; applications can instead request installed packages with SIOXX_USE_SYSTEM_BOOST and SIOXX_USE_SYSTEM_JSON.

It installs an exported target, so a consumer can use:

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

Both static and shared builds are supported. A Conan 2 recipe and consumer tests are included in the repository. CMake presets exercise installation, find_package() consumption, and add_subdirectory() integration.

Tests and CI

The GoogleTest unit suite covers parsers, namespaces and socket bookkeeping, acknowledgements, Engine.IO framing and heartbeat behavior, URL parsing, polling framing, and reconnection policy without opening real sockets.

An opt-in end-to-end suite starts dedicated Node.js Socket.IO servers and verifies WebSocket and polling connections, automatic fallback, JSON and MessagePack interoperability, events and acknowledgements, binary payloads with both built-in parsers, multiple namespaces, and reconnection after an unexpected server shutdown.

GitHub Actions builds and tests on Linux with GCC and Clang, macOS with Clang, and Windows x64 and ARM64 with MSVC. Separate workflows cover CMake integration, Conan packaging, documentation, coverage, and Coverity analysis. A v* tag creates a release only after the build, integration, and packaging jobs succeed.

Try it

sudo apt install cmake ccache libssl-dev
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 matching Node.js server lives under examples/basic_client/server:

cd sioxx/examples/basic_client/server
pnpm install
pnpm start          # JSON
# or: pnpm start:msgpack
# or: pnpm start:cbor
# or: pnpm start:polling

The optional Qt chat example provides a more complete integration example.

Current limitations

sioxx is still a focused client library rather than a complete port of the JavaScript Socket.IO ecosystem. In particular, it does not provide a Socket.IO server, and HTTP long-polling sessions are not upgraded to WebSocket after connection.

Issues and pull requests are 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.