Server

The Application class is the central part of the Harpia framework. It handles the HTTP server, routing, middleware execution, and static file serving.

Getting Started

To create a new server instance, you simply use the default export from the core package.

import harpia from "@harpiats/core";

const app = harpia();

app.get("/", (req, res) => {
  res.send("Hello Harpia!");
});

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

Methods

listen

Signature: listen(options: ServerOptions, callback?: () => void)

Starts the HTTP server. It wraps Bun.serve and provides additional validation.

app.listen({ 
  port: 3000, 
  hostname: "0.0.0.0" 
}, () => {
  console.log("Listening...");
});

Server Options

• port: The port number (1-65535).
• hostname: The hostname to bind to (defaults to localhost).
• development: Enables development mode features.
• unix: Path to a Unix domain socket (cannot be used with port).
• tls: Configuration for HTTPS (see TLS Options).
• maxRequestBodySize: Limit for request body size in bytes.
• reusePort: Enables SO_REUSEPORT (Linux only).

stop

Signature: stop()

Stops the server instance immediately.

app.stop();

use

Signature: use(handler: Handler)

Registers a global middleware that runs for every request.

app.use((req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
});

static

Signature: static(path: string)

Configures the directory for serving static files.

app.static("./public");

setNotFound

Signature: setNotFound(handler: Handler)

Defines a custom handler for 404 Not Found errors.

app.setNotFound((req, res) => {
  res.status(404).send("Page Not Found");
});

TLS Options

Harpia supports HTTPS out of the box using Bun’s native TLS support.

app.listen({
  port: 443,
  tls: {
    key: Bun.file("./key.pem"),
    cert: Bun.file("./cert.pem"),
  }
});