Cerver

A lightweight, compile-time web framework that transpiles restricted JavaScript server logic into highly optimized native C HTTP server binaries.

Cerver takes a Next.js-style file-based routing structure (written in a strict subset of JavaScript), parses it, generates equivalent C code, embeds your static assets, and compiles it all into a single, standalone executable that runs with zero Node.js dependency.

Features

• Compile-Time Framework: Your JavaScript is parsed and compiled to native C. There is no JavaScript engine (like V8) or interpreter included in the final binary.
• Microscopic Footprint: Generated executables are tiny and start in milliseconds.
• Single-Binary Deployment: Static assets (HTML, CSS, JS, images) are automatically minified and embedded directly into the executable as C byte arrays.
• Native Performance: Uses kqueue (macOS) or epoll (Linux) event loops for high-performance non-blocking I/O.
• File-Based Routing: Intuitive routes/ directory structure, supporting dynamic segments (e.g., /item/[id].js).

Benchmarks (Autocannon)

Local loopback runs against localhost, 20s per run.

Note: timeouts only appear at the highest concurrency (240 connections). On a single machine, autocannon and the server compete for CPU and kernel resources; the timeouts are likely client/loopback saturation rather than server errors.

| Connections | Pipelining | Avg req/s | Avg latency | p99 latency | Total read | Errors (timeouts) | | ----------- | ---------- | --------- | ----------- | ----------- | ---------- | ----------------- | | 60 | 1 | 123,005 | 0.01 ms | 0 ms | 21.0 GB | 0 | | 60 | 10 | 125,973 | 4.26 ms | 10 ms | 21.5 GB | 0 | | 120 | 1 | 124,214 | 0.15 ms | 1 ms | 21.2 GB | 0 | | 120 | 10 | 131,245 | 8.64 ms | 15 ms | 22.4 GB | 0 | | 240 | 1 | 124,890 | 0.54 ms | 1 ms | 21.3 GB | 118 (timeout) | | 240 | 10 | 123,677 | 9.87 ms | 14 ms | 21.1 GB | 1540 (timeout) |

Getting Started

1. Install globally (requires gcc or clang on your system):

npm i @velox0/cerver@latest

2. Create a new project:

cerver new my-fast-api
cd my-fast-api

3. Build and Run:

cerver build
cerver run

Routing

Routes are defined in the routes/ directory.

routes/index.js (maps to /)

export function GET(req, res) {
  return res.html(200, "<h1>Hello World!</h1>");
}

routes/api/status.js (maps to /api/status)

export function GET(req, res) {
  return res.json(200, '{"status": "online"}');
}

routes/users/[id].js (maps to /users/:id)

export function GET(req, res) {
  const userId = req.params.id;
  return res.text(200, "User ID: " + userId);
}

Clean URL Asset Mapping

Cerver has a special asset routing convention that prevents folder clutter:

• Root Index: public/index.html is automatically served at the root /.
• Directory Indexing: Nested index.html files inside directories (e.g. public/page/index.html) are not implicitly aliased to /page (they remain at /page/index.html).
• Clean Folder Slugs: If an HTML file has the exact same name as its parent directory, it is mapped to the clean directory URL. For example:
  • public/about/about.html maps to /about (and /about/)
  • public/blog/posts/posts.html maps to /blog/posts (and /blog/posts/)
• Other Static Assets: All other assets like CSS, JS, images, and non-directory-matching HTML files serve directly at their file paths (e.g., public/about/style.css maps to /about/style.css).

The Request & Response Objects

Because Cerver compiles to C, the API surface is restricted.

Request (req)

• req.path — The request URL path
• req.method — The HTTP method
• req.headers["user-agent"] — Access request headers
• req.query.search — Access URL query parameters
• req.params.id — Access dynamic path segments

Response (res)

• res.text(status, string) — Send plain text
• res.json(status, string) — Send JSON
• res.html(status, string) — Send HTML

Supported JavaScript

Cerver supports a strict, synchronous subset of JavaScript suitable for C code generation:

• if/else statements
• const / let variable declarations
• String and Number literals
• Template literals
• Basic comparisons (===, !==, <, >)

Not Supported (Compile-Time Errors):

• async/await and Promises
• Loops (for, while)
• Classes and the new keyword
• eval()
• Runtime import/require

Configuration

cerver.config.js:

export default {
  port: 8080, // Default port
  embed: true, // Embed assets from public/ into the binary
  minify: true, // Minify HTML/CSS/JS before embedding
  compression: "none", // Future: pre-compress assets
};

How It Works

1. Parser: Uses Acorn to parse your JS route files into ASTs.
2. Validator: Scans the AST to ensure no unsupported JS features are used.
3. IR: Transforms the AST into an Intermediate Representation.
4. Generator: Emits optimized C code mapping directly to your JS logic.
5. Asset Pipeline: Scans the public/ folder, minifies files, and converts them to C byte arrays.
6. Compiler: Invokes gcc or clang to compile the generated code and the Cerver runtime into a native binary.