Nova

A high-performance, filesystem-based web framework built specifically for the Lune runtime.

Table of Contents

• Nova
  • 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/:id	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
485864	6076.22 req/s	21.31ms	16.77ms	9.02ms	40.92ms	99.00%	282	0.74 MB/s

🖥️ Container Resource Usage (during benchmark)

Peak CPU	Avg CPU	Peak Memory	Avg Memory %
136.61%	47.09%	71.93MiB	0.21%

Last Benchmarked: Sun Mar 15 04:32:58 UTC 2026