https://github.com/duckonaut/reluax

A web framework based on a custom dialect of Lua
https://github.com/duckonaut/reluax

lua rust server

Last synced: 10 days ago
JSON representation

A web framework based on a custom dialect of Lua

• Host: GitHub
• URL: https://github.com/duckonaut/reluax
• Owner: Duckonaut
• Created: 2024-01-11T14:29:50.000Z (10 months ago)
• Default Branch: main
• Last Pushed: 2024-01-29T16:08:10.000Z (9 months ago)
• Last Synced: 2024-10-11T02:52:36.669Z (27 days ago)
• Topics: lua, rust, server
• Language: Rust
• Homepage:
• Size: 126 KB
• Stars: 3
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        


# Reluax

![Crates.io Version](https://img.shields.io/crates/v/reluax)

`reluax` lets you easily create dynamic websites in a custom dialect of Lua,

inspired by JSX. The service has been written in Rust, and uses `luajit` as

its Lua runtime for performance and ease of integration of other libraries.

## Requirements

- `luajit`

## Installation

Currently, the project is only supported on Linux and MacOS.

Reluax is available through GitHub releases as a prebuilt binary, or

from `crates.io` through `cargo install reluax`, if you have the Rust

toolchain installed. Alternatively, it is packaged as a Nix flake:

if you have Nix installed, you can `nix run github:Duckonaut/reluax`.

## Usage

```

Commands:

  serve  Serve a directory of LuaX files in production mode

  build  Build a directory of LuaX files

  dev    Serve a directory of LuaX files in development mode

  new    Create a new project

  init   Initialize a new project in the current directory

  help   Print this message or the help of the given subcommand(s)

Options:

  -h, --help  Print help

Examples:

  reluax serve

  reluax serve --port 4000

  reluax dev -P public/ -C luax/

```

To create an example project, run `reluax new my-first-project`.

## Inspiration

The project was heavily inspired by Ben Visness' blog post,

[I made JSX for Lua (because I hate static sites)](https://bvisness.me/luax/),

which I highly recommend reading.

## API

A Reluax project is very simple. Reluax expects to run a directory of files,

with the entry point being `reluax.luax` or `reluax.lua`. This module needs

to return a table containing the member function `route`, and optionally a

project name under the key `name`. For code examples, check the

[examples](https://github.com/Duckonaut/reluax/tree/main/example) directory.

The `route` function will be called with the path and, optionally, method and

body of a request, and can return a variety of responses, by returning two

values: the status code, and the response body.

The response body will usually be a table, and by default will be treated as a HTML

page (see `example/basic/`). It can be optionally wrapped using the functions

`reluax.html` or `reluax.json`, the first of which will make sure the HTML is returned

as is, without a `` tag, and the second returning the table as a JSON

object.

With this you can build a rather powerful backend, handling templating, routing, and

anything else through LuaX code.

The `reluax` global table contains several utility functions, described below:

- `reluax.json`: wrap the table to be interpreted as a JSON response,

- `reluax.html_page`: wrap the table to be interpreted as a full HTML page (default behavior),

- `reluax.html`: wrap the table to be interpreted as a HTML excerpt (for e.g. use with

  [htmx](https://htmx.org)),

- `reluax.path_matches`: check if a path string matches the template,

- `reluax.path_extract`: extract named path parameters from the path.