# uWebSockets: a C++ HTTP and WebSocket server with a Node.js binding

> uWebSockets is a C and C++ server library built on the uSockets foundation, with an SSLApp API, a URL router and pub/sub for WebSockets. It is aimed at real-time backends that need to handle many concurrent connections, and it ships a separate Node.js binding called uWebSockets.js.

**uNetworking/uWebSockets** — Simple, secure & standards compliant web server for the most demanding of applications

- Repository: https://github.com/uNetworking/uWebSockets
- Stars: 18,993 · Forks: 1,868
- Language: C++
- License: Apache-2.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/unetworking-uwebsockets

## What uWebSockets solves and who it is aimed at

Most web frameworks treat WebSockets as an add-on bolted onto an HTTP stack that was designed for request and response cycles. uWebSockets inverts that: the README describes it as a web server for "the most demanding of applications", and the feature list leads with TLS 1.3 messaging, a URL router with wildcard and parameter support, and pub/sub for WebSockets. Those three things are what a chat service, a trading feed or a multiplayer game backend actually needs, and they are present in the core library rather than assembled from plugins.

The audience is narrow and specific. The README states that uWebSockets powers several large crypto exchanges and that it has been standards compliant with a perfect Autobahn|Testsuite score since 2016. That claim is about a test suite result, not about your workload, but it tells you the project was built for long-lived connections under load rather than for a blog with a contact form. If your application is mostly rendering pages, the router and pub/sub machinery are weight you will not use.

There is also a scripting path. The README says the library is written entirely in C and C++ but has integration for Node.js backends through a separate project, uWebSockets.js. So the same core is reachable from two very different development styles: compile a C++ binary, or write JavaScript against the binding.

## The SSLApp, router and pub/sub mechanism

The README's own example is the clearest description of the architecture. An SSLApp is constructed with certificate and key file names, routes are registered by chaining .get() and .ws() calls, and the app is started with .listen() and .run(). Handlers are lambdas that receive a response pointer and a request pointer. The comment above the example states that you should have one app per thread, spawn as many as you have CPU cores, and let uWS share the listening port. That is the concurrency model: threads, not a single event loop with a thread pool.

Routing supports parameters. The example route "/hello/:name" reads the value with req->getParameter("name"), and the README says the router supports wildcards as well as parameters. Responses are written incrementally: writeStatus, writeHeader, write, end. The example comments that you can efficiently stream huge files the same way, which matters because it means a large response does not have to be assembled in memory first.

On the WebSocket side, the .ws<UserData>("/*", ...) call registers handlers including open and message. The open handler in the example calls ws->subscribe("oh_interesting_subject"), and the message handler echoes the incoming payload back. That subscribe call is the pub/sub feature: a socket joins a named subject, and the server can publish to that subject rather than iterating over a connection list itself.

Underneath all of this sits uSockets, which the README describes as a foundation library implementing eventing, networking and cryptography in three layers. Each layer has multiple implementations and you choose the compiled composition with flags. The README lists five event-loop integrations: libuv, ASIO, GCD and raw epoll/kqueue. This is the part of the design that most affects how you build and deploy, and it is also the part the README delegates to another repository.

## Building uWebSockets and running a first server

The README does not give a step-by-step install section. It points to the user manual in misc/READMORE.md and to the examples directory, and it gives two build flag combinations inline. The repository layout confirms this: a GNUmakefile and a Makefile sit at the top level alongside build.c and build.h, and there is an examples directory with files such as HelloWorld.cpp, EchoServer.cpp, ParameterRoutes.cpp and HttpServer.cpp.

The README's first documented build line uses WolfSSL and libuv:

```bash
WITH_WOLFSSL=1 WITH_LIBUV=1 make examples
```

That command builds the example programs with WolfSSL for TLS and libuv for eventing. The README says to see uSockets for an up-to-date list of flags, so treat the two combinations it shows as starting points rather than a complete matrix.

The second documented combination drops WolfSSL and uses the native kernel for eventing:

```bash
WITH_OPENSSL=1 make examples
```

After either build, the example binaries are what you run. The README's inline C++ sample is the shape of a minimal secure server, and it is worth reading before writing your own:

```c++
uWS::SSLApp({
    .cert_file_name = "cert.pem",
    .key_file_name = "key.pem"
}).get("/hello/:name", [](auto *res, auto *req) {
    res->writeStatus("200 OK")
       ->writeHeader("Content-Type", "text/html; charset=utf-8")
       ->write("<h1>Hello ")
       ->write(req->getParameter("name"))
       ->end("!</h1>");
}).listen(9001, [](auto *listenSocket) {
    if (listenSocket) {
        std::cout << "Listening on port " << 9001 << std::endl;
    }
}).run();
```

The listen callback receives a socket pointer, and the example prints a message when it is non-null. The README's fuller version also handles the failure branch, printing that the certs failed to load or the port could not be bound. That failure branch is the first thing to keep when you adapt the sample, because a TLS server that starts without valid certificates is a confusing thing to debug.

On Windows the repository ships an NMake shim. The Makefile comments describe setting environment variables such as WITH_ZLIB, WITH_LTO, CC, CXX, CFLAGS, LDFLAGS, EXEC_SUFFIX and WITH_LIBUV before running nmake, and note that the shim is a work in progress. That last word matters: the Windows path is the less travelled one.

## Where uWebSockets is the wrong choice

The README is a project pitch, and it is thin on the operational side. It does not document rollback, graceful shutdown, deployment topology or how to drain connections during a restart. If your service must be restarted without dropping clients, you will be designing that yourself, and the README will not tell you whether the library helps.

The build story is also a real constraint. Choosing between WolfSSL, OpenSSL and the native kernel, and between libuv, ASIO, GCD and epoll/kqueue, is a compile-time decision that changes what your binary links against. The README explicitly sends you to uSockets for the flag list, which means the authoritative build documentation lives in a different repository from the one you are reading. Teams that expect a package manager to resolve this for them will be disappointed.

The Node.js story has the same shape. The README points to uWebSockets.js for rapid scripting, but that is a separate repository with its own documentation, its own TypeDoc and its own release cadence. If you want the JavaScript binding, you are adopting two projects, not one.

Finally, the README's compliance and performance claims point outward, to an Autobahn report PDF, to a benchmarks directory, to an OSS-Fuzz badge and to a screenshot of fuzzing coverage. Those are useful signals that the project takes correctness and fuzzing seriously, but they are the project's own published artifacts. Nothing in the README tells you how the library behaves under your specific message sizes, connection churn or TLS configuration.

## uWebSockets compared with ws and Socket.IO

The closest comparisons in the Node.js world are ws, a WebSocket implementation, and Socket.IO, which layers a protocol with fallbacks and reconnection on top of WebSockets. The difference in approach is where the server logic lives. ws gives you a WebSocket server and leaves routing, HTTP handling and pub/sub to you or to other packages. Socket.IO gives you a higher-level protocol with rooms and events, but it is not a plain WebSocket endpoint, so a browser client must use the matching Socket.IO client.

uWebSockets sits between those positions. It is a full HTTP and WebSocket server with a router and pub/sub built in, but it speaks standard WebSockets, which is what the README means when it cites a perfect Autobahn|Testsuite score and standards compliance. You are not opting into a custom wire protocol. The cost is that you take on a compiled dependency and its build flags rather than installing a pure JavaScript package.

Against Go servers, the trade is different again. Go gives you goroutines and a garbage collector; uWebSockets gives you C++ with explicit thread management, as the README's "one app per thread" comment shows. That is a deliberate choice in favour of control over per-connection memory, and it is also why the library's audience skews toward teams with existing C++ infrastructure.

## Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-18. Recent releases are v20.80.0 on 2026-09-03, v20.79.0 on 2026-07-06 and v20.78.0 on 2026-05-31. The README notes the project has been on GitHub since 2016, and it credits several companies for supporting it. There is also a commercial angle: uNetworking AB is described as a Swedish consulting and contracting company dealing with anything related to uWebSockets, including development, support and customer success, with an email address given for business inquiries. That is relevant to upgrade planning, because a project with a paid support channel behind it behaves differently from one maintained purely by volunteers.

The licence is Apache-2.0, and the README's own wording is worth reading closely. It says that where such explicit notice is given, source code is licensed under Apache License 2.0, and that modified forks should consist of nothing but licensed source code and be made available under another product name. It also states that intellectual property is otherwise reserved and asks you to ask before assuming. That is not the boilerplate you find in most Apache-2.0 projects, and it is a signal that the maintainers care about how forks are presented. This is not legal advice; if you plan to fork or rebrand, read the LICENSE file and the README notice together and get your own answer.

Upgrade cost is dominated by the build flags rather than by API churn. Because the eventing and crypto layers are selected at compile time, a change in your flag combination can change your linked libraries and your deployment artifact. The README does not publish a compatibility policy for these flags.

## Conclusion

Adopt uWebSockets if you are building a real-time C++ or Node.js backend and are willing to compile the library yourself with the documented WITH_* flags, since the README points to uSockets for the up-to-date flag list. Do not adopt it if you need a plain HTTP framework with middleware, template engines or a large package ecosystem, because the README describes a router and pub/sub rather than an application framework. Before committing, verify the SSLApp certificate options you need against the uSockets documentation, confirm which event loop integration you will compile against, and check the examples directory for a sample close to your use case.

## FAQ

### How do I install uWebSockets for C++?

The README does not give a package-manager install. It points to the user manual in misc/READMORE.md and to the examples directory, and it shows two build flag combinations, WITH_WOLFSSL=1 WITH_LIBUV=1 make examples and WITH_OPENSSL=1 make examples, run against the repository's GNUmakefile. It then refers you to uSockets for the up-to-date list of flags.

### How do I use uWebSockets in a first server?

The README's inline example constructs a uWS::SSLApp with cert_file_name and key_file_name, registers a route with .get("/hello/:name", ...) that reads req->getParameter("name"), registers WebSocket handlers with .ws<UserData>("/*", ...), and finishes with .listen(9001, ...) and .run(). The listen callback receives a socket pointer that is null when the certs fail to load or the port cannot be bound.

### What is the difference between uWebSockets and uWebSockets.js?

uWebSockets is the C and C++ library. The README says it has integration for Node.js backends through uWebSockets.js, a separate project it links to for rapid scripting, with its own TypeDoc and Autobahn report.

## Sources

- [Issues](https://github.com/uNetworking/uWebSockets/issues)
- [License: Apache-2.0](https://github.com/uNetworking/uWebSockets/blob/master/LICENSE)
- [README](https://github.com/uNetworking/uWebSockets/blob/master/README.md)
- [Releases](https://github.com/uNetworking/uWebSockets/releases)
- [uNetworking/uWebSockets on GitHub](https://github.com/uNetworking/uWebSockets)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/unetworking-uwebsockets