A Node.js HTTP framework with a C++17 native engine (kqueue / epoll, SO_REUSEPORT workers, radix-trie router). The JavaScript API looks like a small Express app. The bytes on the wire are parsed and, for static routes, answered in C++.

Docs: https://moaaz-i.github.io/Velociradix · Trust: SECURITY.md · Releases: VERSIONING.md

What this is

• An HTTP/1.1 server for Node 20+ with zero npm runtime dependencies.
• A native .node addon. Install uses a prebuild when one exists; otherwise it compiles.
• Fast static responses via fastGet / fastPost (C++ writes the bytes; V8 is not involved).
• A JS handler path (app.get, middleware, ctx.json) for real application code.

What this is not

• Not a drop-in Express or Fastify. velociradix/express is a compatibility shim, not Express.
• Not faster than Fastify on a normal JS JSON route. On that workload Fastify wins in our own numbers below.
• Not a WebSocket server. app.ws() was removed; it never did a 101 upgrade.
• Not a GraphQL server. app.graphql() is an experimental POST-only helper.
• Not llhttp. The HTTP parser is custom C++. That is a trust decision, not a footnote.

If you need the Node ecosystem, stick with Fastify or Express. If you need a real WebSocket, use a dedicated library. If you need a static /health that never enters V8, fastGet is the reason this engine exists.

Trust (read this before production)

Velociradix puts a custom C++ HTTP parser and a native addon on the public internet.

• A bug in the parser or the addon can smuggle requests or crash the process (segfaults are not try/catch).
• The parser is not llhttp. It has smuggling and DoS guards (see SECURITY.md); that is not the same as a widely fuzzed library parser.
• Use 8.2.0 or newer on the public internet. 8.2.0 closed known 8.1.1 issues (reject all Transfer-Encoding, keep-alive idle timeout, napi_external handles, realpath static files, IPv6 accept).
• Official npm publishes use GitHub Actions OIDC provenance. You are still trusting this repository’s C++ and the prebuilt .node files.
• Zero npm dependencies reduces JS supply chain. It does not remove native-binary risk.

Report vulnerabilities privately: SECURITY.md.

Benchmarks (same work, labeled)

Numbers from autocannon on Apple Silicon: 100 connections, pipelining 10, GET /json returning a small JSON body. Logger middleware off.

JavaScript handlers (this is the app you actually write)

| Server | RPS (approx.) | | :----------------------------- | ------------: | | Fastify v4.28 | ~68,000 | | Velociradix app.get (JS) | ~54,000 | | Express v4.19 | ~11,500 |

About 80% of Fastify on a lean () => ({ … }) JSON handler, ~4.5× Express. Reproduce: node bench/bench-json.mjs.

C++ static path (not the same work)

| Server | RPS | Avg latency | | :------------------------ | ----------: | ----------: | | Velociradix fastGet | 114,490 | 8.26 ms |

fastGet serves a preformatted JSON/text body from C++ memory. There is no JS callback, no serialization per request, no middleware. Do not compare it to Fastify or Express handlers. Use it for /health, /ping, and other immutable payloads.

Reproduce: npm run bench (addon vs node:http microbench) and the methodology in docs/guide/benchmarks.md.

Install

npm install velociradix

Requires Node.js ≥ 20. Prebuilds: Linux x64, macOS arm64, Windows x64. Other platforms compile from source (make).

Installs the latest release on npm. 8.x is the stability line — there will not be a 9.0 until a real breaking change with a migration window. See VERSIONING.md.

Quick start

import { createApp, helmet } from "velociradix";

const app = createApp();

app.use(helmet());

app.fastGet("/health", { ok: true });

app.get("/", (ctx) => {
  return { message: "Hello from Velociradix" };
});

app.get("/users/:id", (ctx) => {
  return { userId: ctx.params.id, search: ctx.query("q") };
});

app.listen(3000, () => {
  console.log("http://localhost:3000");
});

TypeScript:

import { createApp, type Context, BadRequestError } from "velociradix";

const app = createApp();

app.get("/users/:id", async (ctx: Context) => {
  const id = Number(ctx.params.id);
  if (!Number.isFinite(id)) {
    throw new BadRequestError("User ID must be a number");
  }
  return ctx.json({ id, name: "Moaaz" });
});

app.listen(3000);

Scaffold (optional): npx create-velociradix-app my-api

Core API

app.get("/items", (ctx) => ctx.json([1, 2, 3]));
app.group("/api/v1", (v1) => {
  v1.get("/ping", (ctx) => ctx.send("pong"));
});
app.fastGet("/ping", "pong");

SSE:

app.get("/events", (ctx) => {
  ctx.sse((stream) => {
    stream.send({ event: "ping", data: "connected" });
    stream.close();
  });
});

JWT (secret from the environment, never from source):

import { jwtAuth } from "velociradix";

app.get("/admin", (ctx) => ({ user: ctx.state.user }), {
  middlewares: [jwtAuth({ secret: process.env.JWT_SECRET })],
});

Static files in production need { root }. Swagger / metrics / Postman UI need { expose: true } on a non-local NODE_ENV. Details: security guide.

Optional extras

These exist. They are not the product. Stability and threat model vary; read the linked page before using them in production.

| Area | Import / API | Notes | | :-------------------------------------- | :---------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | | Express shim | velociradix/express | Express-shaped API on Velociradix core — see express guide | | RPC client | velociradix/client | Typed path-chaining HTTP client | | Decorators | velociradix/decorators | Optional OOP style | | Built-in middleware | helmet, cors, rateLimit, … | Use what you need; do not stack “all of them” | | OpenAPI UI | app.swagger(), app.postmanDoc() | Gated in production | | EventBus / file routes / GraphQL helper | see docs | GraphQL is experimental |

Full list: features.

Supported prebuilds

| OS | Arch | Status | | :------ | :---- | :------- | | Linux | x64 | Prebuilt | | macOS | arm64 | Prebuilt | | Windows | x64 | Prebuilt |

Contributing and issues

If something breaks, open a GitHub issue. Silence is not a health metric.

• Bugs and questions: github.com/Moaaz-i/Velociradix/issues
• How to report: CONTRIBUTING.md
• Security: SECURITY.md

License

MIT. See LICENSE.