bizwiz3/nova

Table of Contents

• Table of Contents
• Installation & Usage
  • Manual Installation
    • Usage
  • Install a boilerplate
• Core Features
• Route Definition
• Routing Conventions
• Middleware Chaining
• Performance Benchmarks
  • Latest Performance (Auto-updated)
    • 📊 HTTP / k6 Metrics
    • 🖥️ Container Resource Usage (during benchmark)

Installation & Usage

Manual Installation

Manually install Nova via the Pesde package manager:

pesde add bizwiz3/nova
pesde install

Usage

In your root project or src/ directory, create your entry file.

Example: index.luau

Paste the code below:

local Nova = require("@path/to/nova")

local app = Nova.new(8080)

app:listen() -- To run the server

Install a boilerplate

Installing a boilerplate for much easier setup

pesde x bizwiz/nova_setup
pesde install

Core Features

• Filesystem Routing: Routes are automatically mapped to the directory structure of the app folder.
• Pattern Matching: Native support for dynamic segments using [params] syntax.
• Middleware Pipeline: Functional middleware chaining for global and route-specific logic.
• Unified Response Utility: Standardized handling for JSON and HTML content types.
• Environment Management: Automatic .env loading and process injection.
• Integrated Logger: Colored terminal output for request monitoring and debugging.

Route Definition

Nova organizes routes by folder. To create a route at /, you must create an app/ directory first in your root project or src/ directory.

Create a luau file inside the app/ directory and name it route.luau.

Should look like this:

project-dir/
├── src/
    ├── app/
    |   └── route.luau
    └── index.luau    

Or like this

project-dir/
├── app/
|    └── route.luau
└── index.luau

Paste the code below inside the route.luau:

local Nova = require("@path/to/nova")

local App = {}

function App.Get()
    return Nova.response({ msg = "Hello, Nova" })
end

return App

The Module name App itself does not matter, but it must have Get, Post, etc. as its public function.

Routing Conventions

Nova follows a predictable mapping from the filesystem to the URL path:

Path	Filesystem Map
/	app/route.luau
/users	app/users/route.luau
/posts/	app/posts/[id]/route.luau

Middleware Chaining

Utilize the chain helper to apply logic sequentially before a request reaches the final handler:

local Nova = require("@path/to/nova")

local function validate(req, next)
    if not req.headers["x-api-key"] then
        return Nova.response({ error = "Forbidden" }, { status = 403 })
    end
    next()
end

Route.Get = Nova.chain({ validate }, function(req)
    return Nova.response({ data = "Authorized access" })
end)

More info about middlewares soon.

Performance Benchmarks

Latest Performance (Auto-updated)

📊 HTTP / k6 Metrics

Total Requests	Requests/sec	p95 Latency	p90 Latency	Median Latency	Avg Latency	Success Rate	Failed Requests	Throughput
458895	5736.82 req/s	19.95ms	15.85ms	8.73ms	44.45ms	99.00%	288	0.70 MB/s

🖥️ Container Resource Usage (during benchmark)

Peak CPU	Avg CPU	Peak Memory	Avg Memory %
134.39%	43.35%	74.04MiB	0.21%

Last Benchmarked: Wed Mar 18 07:26:43 UTC 2026