Skip to content

Performance & Optimization

Jump to bottom
Nadhi-(Kushi) edited this page Apr 1, 2026 · 2 revisions

Performance & Optimization

This page describes the optimization paths that exist in the current codebase. It does not hardcode benchmark numbers, because those change with runtime, platform, version, and workload.

Static Fast Path

app.static() is the most explicit exact-route fast path:

app.static("/about", "<html><body>About</body></html>");

These routes are compiled into the manifest and can be served directly by the native router.

Native Response Cache

res.ncache() stores a JSON response in the native cache:

app.get("/config", async (req, res) => {
  const config = await loadConfig();
  res.ncache(config, 60, { maxEntries: 256 });
});

Notes:

  • ttl is in seconds
  • the cache is route-scoped in native code
  • cached responses bypass the normal JS dispatch path

Runtime Optimizer

Server handles expose optimizer state:

const server = await app.listen().port(3000);

console.log(server.optimizations.summary());
console.log(server.optimizations.snapshot());

Route snapshots include fields like:

  • staticFastPath
  • binaryBridge
  • bridgeObserved
  • cacheCandidate
  • dispatchKind
  • timing metrics when enabled

Request Access Analysis

The runtime analyzes handler access so the bridge can avoid collecting more request data than a route needs.

Router Shape

  • exact static routes are handled as direct lookups
  • param routes compile with param metadata and segment matching

Dev Diagnostics

You can enable optimizer/log output through createApp({ dev: { logger: true } }).

When enabled, the runtime can emit route optimization summaries and optional route comments.

Benchmarks

Benchmark harness files live under .github/bench/.

Manual runner:

bun .github/bench/run.js http-native static 3001 bun

CI runner:

bun .github/bench/ci.js --engines=http-native,bun,express --scenarios=static,dynamic,opt

Current benchmark coverage includes:

  • http-native
  • bun
  • express

Practical Guidance

  • Use app.static() for pre-rendered exact HTML routes.
  • Use res.ncache() for deterministic JSON that should stay in the native cache.
  • Keep middleware scoped when possible.
  • Avoid reading body or headers in handlers that do not need them.

Http-native is open to everyone, but we have strict regulations and licensing fees for large organizations

Getting Started

Core Concepts

Middleware

Advanced

Community

Clone this wiki locally