swm-uws: native uWebSockets binding for Node.js

Installation and quick start

Shellinstall

npm install @swarmmachina/swm-uws

JavaScriptquick-start.js

import uWS from '@swarmmachina/swm-uws'

const app = uWS.App()

app.get('/', (res) => {
  res.writeHeader('content-type', 'application/json')
    .end('{"ok":true}')
})

app.ws('/ws', {
  message(ws, message, isBinary) {
    ws.send(message, isBinary)
  }
})

app.listen(3000, (socket) => {
  if (!socket) process.exit(1)
})

Default import, CommonJS require, and the App / us_listen_socket_close named imports are available.
app.close() is idempotent and closes active HTTP and WebSocket contexts.
The complete TypeScript surface is declared in lib/index.d.ts.

Supported surface

HTTP routing: get, post, put, patch, del, options, head, connect, trace, and any.
Streaming: write, tryEnd, onWritable, onData, collectBody, pause/resume, and cork.
WebSocket: Lifecycle callbacks, sends, fragmented sends, ping, topics, and pub/sub.
Network addresses: Remote and PROXY protocol addresses, ports, listen options, and Unix sockets.
Optional fast paths: capabilities() reports endBatch, beginWrite, collectBody, and other available accelerations.
Explicit boundaries: SSLApp/TLS, H3App, permessage-deflate, SNI, and experimental KV/timer helpers are not implemented.

Runtime and platforms

Environment	Status	Note
Node.js 22 / 24	Supported	Prebuilds are released for supported ABIs.
Linux x64 + glibc	Supported	Portable generic x86-64 build.
Windows x64	Supported	A native build is included in the package.
macOS arm64 / x64	Supported	Apple Silicon and Intel are supported.
Windows ARM64	Unsupported	There is no current prebuild.
Alpine / musl	Unsupported	A glibc environment is required.
TLS / permessage-deflate	Disabled	Terminate TLS in front of the application.

API map

TemplatedApp

Routes, listen operations, WebSocket behavior, and pub/sub.

get()post()put()patch()del()options()head()any()ws()publish()numSubscribers()listen()listen_unix()filter()close()

HttpRequest / HttpResponse

Request data, snapshots, and streamed responses.

getMethod()getUrl()getHeader()getQuery()getParameter()forEach()snapshot()writeStatus()writeHeader()end()write()tryEnd()onWritable()onData()collectBody()onAborted()

WebSocket

Messages, fragments, backpressure, and topics.

send()sendFirstFragment()sendFragment()sendLastFragment()ping()publish()cork()end()close()getBufferedAmount()getRemoteAddress()getUserData()subscribe()unsubscribe()isSubscribed()getTopics()

Complete signatures, types, and examples are available in the source repository README and TypeScript declarations.

Lifetime and memory ownership

The binding stays close to native uWS, so wrapper and buffer lifetimes are part of the API contract.

Snapshot before await

HttpRequest is valid only inside a route or upgrade callback. Call req.snapshot(paramCount) before asynchronous work.

Zero-copy requires discipline

onData and onDataV2 receive a zero-copy ArrayBuffer that is detached after the callback. Copy a chunk if it is needed later.

Owned body

collectBody(maxSize, callback) returns an application-owned ArrayBuffer, or null when the limit is exceeded.

Extending response lifetime

A Response remains valid after the route callback only when onData, onWritable, collectBody, or onAborted is registered.

Terminal callbacks

Response and WebSocket wrappers are already invalid inside onAborted and close callbacks respectively.

Drop-in alias for uWebSockets.js

If an application uses the supported regular App() surface, install the package under the original name. SSLApp, H3App, compression, SNI, and experimental APIs require an explicit migration.

Shellinstall alias

npm install uwebsockets.js@npm:@swarmmachina/swm-uws

JavaScriptserver.js

// The original import stays unchanged
import uWS from 'uwebsockets.js'

Need request contexts, routing, body limits, and graceful shutdown?Open swm-core