Decision record · server stack
swm-core or swm-uws for Node.js?
Short answer
Use swm-core for an application HTTP/WebSocket service: it adds routing, request contexts, body budgets, selective header prefetch, an explicit trusted-proxy policy, timeouts, backpressure, and graceful shutdown. Use swm-uws when you need a compatible low-level uWebSockets.js API and the team is prepared to own the server lifecycle.
- 5.1.2
- swm-core
- 0.7.3
- swm-uws
- 22 / 24
- Node.js
Scope
This comparison fixes @swarmmachina/swm-core at 5.1.2 and @swarmmachina/swm-uws at 0.7.3 for Node.js 22/24. Both packages use MPL-2.0.
Server stack layer comparison
| Criterion | swm-core | swm-uws |
|---|---|---|
| Layer | A ready HTTP/WebSocket server layer. | A native V8 binding for the compatible non-TLS uWebSockets.js surface. |
| HTTP | Routes, before hooks, contexts, body parsing, CORS, and static helpers. | App.get/post/any with direct request and response callback ownership. |
| WebSocket | Upgrade contract, context, pub/sub, connectionKey, and managed termination. | App.ws behavior and low-level WebSocket callbacks. |
| Resources | Body budgets, per-route limits, header prefetch, async timeout, trusted proxy, transport policy, and context pools. | Per-App parser/time limits and counters; aggregate body budgets and admission control stay application-owned. |
| Shutdown | shutdown(timeout) drains active work; close() terminates immediately. | The team coordinates the listen socket, requests, and connections. |
| Ownership cost | More ready contracts and less application infrastructure. | Fewer abstractions but more lifecycle code and tests to own. |
Choose from the task
- 01
A normal production API or WebSocket gateway
Start with swm-coreServer limits and termination are already part of its contract.
- 02
Porting an existing uWebSockets.js application
Consider swm-uwsIt offers a compatible non-TLS API and an npm alias for uwebsockets.js.
- 03
Building a custom framework layer
Build on swm-uwsOnly when the team explicitly owns routing, safety, shutdown, and regression tests.
Checks before choosing
- Both packages support only their documented Node.js and prebuilt platform matrix.
- TLS terminates before the application; Alpine/musl is outside the current build matrix.
- Enable trustedProxy only behind an ingress that overwrites the selected header; X-Forwarded-For requires an exact hops count.
- A lower-level API does not automatically reduce total system cost.
Primary sources
Contracts were checked against the README and package metadata for fixed releases.