Home / API Reference / nixi Module

nixi Module API

The nixi module provides layout helpers, response utilities, and template rendering functions. This is the main entry point that combines init, component, and animation modules.

Layout Helpers

Layout(props)

Wraps content in a complete HTML document with doctype and standard head elements.

Nixi.Layout(props)

Parameters:

Returns: string - Full HTML document

app:get("/", function(ctx)
    return Nixi.Layout({
        title = "My Page",
        body = Nixi.div({ class = "container" },
            Nixi.h1(nil, "Welcome")
        )
    })
end)

Output:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Page</title>
    <script src="https://unpkg.com/htmx.org@1.9.10"></script>
    <link rel="stylesheet" href="/public/style.css">
</head>
<body class="nixi-fade-in">...</body>
</html>

Response Helpers

json(data)

Creates a JSON response. Tries cjson first, then dkjson.

Nixi.json(data)

Parameters:

Returns: table - Response object with JSON body

app:get("/api/users", function(ctx)
    local users = {
        { id = 1, name = "Alice" },
        { id = 2, name = "Bob" }
    }
    return Nixi.json(users)
end)

Output:

{
    status = 200,
    headers = { ["Content-Type"] = "application/json" },
    body = '[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]'
}

redirect(path)

Creates a redirect response (302 Found).

Nixi.redirect(path)

Parameters:

Returns: table - Response object for redirect

app:post("/logout", function(ctx)
    return Nixi.redirect("/")
end)

Output:

{
    status = 302,
    headers = { ["Location"] = "/" },
    body = ""
}

error(code, message)

Creates an error response with plain text body.

Nixi.error(code, message)

Parameters:

Returns: table - Response object with error

app:get("/protected", function(ctx)
    if not ctx.locals.authenticated then
        return Nixi.error(401, "Authentication required")
    end
end)

Output for 404:

{
    status = 404,
    headers = { ["Content-Type"] = "text/plain" },
    body = "Not Found"
}

Response Table Structure

All Nixi response helpers return a standardized response table:

FieldTypeDescription
statusnumberHTTP status code (200, 404, etc.)
headerstableKey-value pairs of response headers
bodystringResponse body content

Complete Response Example

local Nixi = require("nixi.init")

local app = Nixi.new({ port = 3000 })

app:get("/", function(ctx)
    return Nixi.Layout({
        title = "Nixi API Demo",
        body = Nixi.div({ class = "container" },
            Nixi.h1(nil, "Nixi API Demo"),
            Nixi.p(nil, "Demonstrating response helpers")
        )
    })
end)

app:get("/api/users/:id", function(ctx)
    local userId = ctx.params.id
    return Nixi.json({
        id = tonumber(userId),
        name = "User " .. userId,
        email = "user" .. userId .. "@example.com"
    })
end)

app:post("/api/users", function(ctx)
    local body = ctx.request.body
    
    if not body.name then
        return Nixi.error(400, "Name is required")
    end
    
    return Nixi.json({
        created = true,
        id = math.random(1000, 9999),
        name = body.name
    })
end)

app:get("/dashboard", function(ctx)
    if not ctx.locals.user then
        return Nixi.redirect("/login")
    end
    
    return Nixi.Layout({
        title = "Dashboard",
        body = Nixi.div({ class = "dashboard" },
            Nixi.h1(nil, "Dashboard"),
            Nixi.p(nil, "Welcome, " .. ctx.locals.user.name)
        )
    })
end)

app:use(function(ctx)
    ctx.locals.requestId = os.time()
end)

return app

return app

Custom Response Headers

Add custom headers to any response:

app:get("/api/data", function(ctx)
    local response = Nixi.json({ data = "value" })
    response.headers["X-Request-ID"] = ctx.locals.requestId
    response.headers["Cache-Control"] = "no-cache"
    return response
end)

UI Module

Access UI components via the nixi.ui module:

local UI = require("nixi.ui")
local theme = require("nixi.ui.theme")

-- Render components
UI.Button.render({ variant = "primary", children = "Click" })
UI.Input.render({ type = "text", label = "Name" })
UI.Card.render({ title = "Card Title", children = "Content" })

Theme System

-- Get available themes
local themes = theme.themes
-- { tokyoNight, dracula, githubDark, catppuccinMocha }

-- Apply a theme
local tokyoNight = theme.getTheme("tokyoNight")
theme.applyTheme(tokyoNight.colors)
theme.injectAllStyles(tokyoNight.colors)

Type Definitions

---@class NixiConfig
---@field host string?
---@field port number?
---@field static_dir string?

---@class Nixi
---@field Layout fun(props: table): string
---@field json fun(data: any): Response
---@field redirect fun(path: string): Response
---@field error fun(code: number, message: string): Response

---@class Response
---@field status number
---@field headers table
---@field body string