Skip to content

API Reference

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

API Reference

This page covers the public API currently exported by @http-native/core.

createApp(config?)

import { createApp } from "@http-native/core";

const app = createApp({
  server: {
    host: "127.0.0.1",
    port: 3000,
    backlog: 2048,
    maxHeaderBytes: 16 * 1024,
  },
  tls: null,
  dev: {
    logger: true,
    hotReload: false,
    hotReloadPaths: ["src"],
    hotReloadDebounceMs: 120,
    devComments: true,
    timing: false,
    cache: false,
  },
});

Application

Route registration

app.get(path, handler);
app.post(path, handler);
app.put(path, handler);
app.delete(path, handler);
app.patch(path, handler);
app.options(path, handler);
app.all(path, handler);

app.use(middleware) / app.use(path, middleware)

Register global or path-scoped middleware.

app.use(async (req, res, next) => {
  await next();
});

app.use("/api", async (req, res, next) => {
  await next();
});

app.group(prefix, callback)

app.group("/api", (api) => {
  api.get("/users", listUsers);
});

app.error(handler) / app.onError(handler) 

app.error(async (error, req, res) => {
  res.status(500).json({ error: error.message });
});

app.static(path, html, options?)

Registers an exact GET HTML route that can be served from the native static fast path.

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

Options:

  • status?: number
  • headers?: Record<string, string>
  • objects?: Record<string, unknown> | null

If objects is provided, the response gets a trailing script that assigns window.hnSSR.objects.

app.reload(options?)

Configures app-level dev reload behavior.

app.reload({
  files: ["src", "routes"],
  debounceMs: 80,
  clear: true,
});

Options:

  • watch?: string[]
  • files?: string[]
  • debounceMs?: number
  • clear?: boolean

app.listen(options?)

Starts the server and returns a chainable ListenHandle.

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

Listen options:

  • host?: string
  • port?: number
  • backlog?: number
  • serverConfig?: HttpServerConfig

ListenHandle

const server = await app.listen().port(3000).tls({
  cert: "./cert.pem",
  key: "./key.pem",
});

Methods:

  • .port(number)
  • .tls({ cert, key, ca?, passphrase? })
  • .hot(true | false | { paths?, hotReloadPaths?, debounceMs?, hotReloadDebounceMs? })

listen().opt() is removed. Runtime options belong in createApp({ dev: ... }).

Request

Properties

  • req.method: string
  • req.path: string
  • req.url: string
  • req.params: Record<string, string>
  • req.query: Record<string, string | string[]>
  • req.headers: Record<string, string>
  • req.body: Buffer | null
  • req.session
  • req.sessionId?: string

Methods

req.header(name);
req.json();
req.text();
req.arrayBuffer();

req.body is raw bytes. Use req.json() when you expect JSON.

Response

Core methods

res.status(code);
res.set(name, value);
res.header(name, value);
res.get(name);
res.type(value);
res.send(data);
res.json(data);
res.html(html, options?);
res.sendStatus(code);

res.html(html, options?)

res.html("<html><body><h1>Hello</h1></body></html>", {
  objects: { user: { id: 1 } },
});

Options:

  • status?: number
  • headers?: Record<string, string>
  • objects?: Record<string, unknown> | null

res.ncache(data, ttl, options?)

Caches a JSON response in the native layer.

res.ncache({ ok: true }, 60, { maxEntries: 256 });
  • ttl is in seconds
  • options.maxEntries defaults to 256

res.locals

Mutable per-request storage shared across middleware and handlers.

ServerHandle

Returned by awaiting app.listen(...).

Properties:

  • host
  • port
  • url
  • tls
  • optimizations

Methods:

  • close()

Optimization helpers:

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

Dev Runtime

Programmatic dev control lives under @http-native/core/dev:

import { createDevServer } from "@http-native/core/dev";

Compatibility wrapper:

import { hot } from "@http-native/core/hot";

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