|
1 | 1 | <div align="center"> |
2 | | - <div> |
| 2 | + <h1> |
3 | 3 | <img height="150" src="./docs/public/nova.png" alt="Nova logo"> |
4 | | - </div> |
5 | | - <br> |
6 | | - <a href="https://pesde.dev/packages/bizwiz3/nova"> |
7 | | - <img src="https://img.shields.io/badge/pesde-bizwiz3/nova-F19D1E?style=flat"> |
8 | | - </a> |
9 | | - <a href="https://github.com/BizWiz3/nova/actions/workflows/ci.yml"> |
10 | | - <img src="https://github.com/BizWiz3/nova/actions/workflows/ci.yml/badge.svg"> |
11 | | - </a> |
| 4 | + </h1> |
12 | 5 | <h3> |
13 | 6 | A filesystem-based web framework for Luau runtimes, with out-of-the-box support for <a href="https://lute.luau.org/" alt="Lute Runtime">Lute</a>, <a href="https://lune-org.github.io/docs/" alt="Lune Runtime">Lune</a> and <a href="https://zune.sh/" alt="Zune Runtime">Zune</a>. |
14 | 7 | </h3> |
| 8 | + <a href="https://pesde.dev/packages/bizwiz3/nova"> |
| 9 | + <img src="https://img.shields.io/badge/pesde-bizwiz3/nova-F19D1E?style=for-the-badge"> |
| 10 | + </a> |
| 11 | + <a href="https://nova-guild.github.io/core/"> |
| 12 | + <img src="https://img.shields.io/badge/nova-documentation-8B5CF6?style=for-the-badge"> |
| 13 | + </a> |
15 | 14 | </div> |
16 | 15 |
|
17 | | -## Table of Contents |
18 | | - |
19 | | -- [Table of Contents](#table-of-contents) |
20 | | -- [Installation \& Usage](#installation--usage) |
21 | | - - [Installation](#installation) |
22 | | - - [Usage](#usage) |
23 | | - - [Manual Setup](#manual-setup) |
24 | | -- [Core Features](#core-features) |
25 | | -- [Routing Conventions](#routing-conventions) |
26 | | -- [Middleware Chaining](#middleware-chaining) |
27 | | - |
28 | | -## Installation & Usage |
29 | | - |
30 | | -### Installation |
31 | | - |
32 | | -Install Nova via the Pesde package manager: |
33 | | - |
34 | | -```sh |
35 | | -pesde add bizwiz3/nova |
36 | | -pesde install |
37 | | -``` |
38 | | - |
39 | | -### Usage |
40 | | - |
41 | | -#### Manual Setup |
42 | | - |
43 | | -1. Create a `src/` directory in your project root. |
44 | | -2. Create an entry file (e.g., `index.luau`) inside `src/` with the following code: |
45 | | - |
46 | | -```lua |
47 | | -local Nova = require("@path/to/nova") |
48 | | - |
49 | | -local app = Nova.new(8080) |
50 | | - |
51 | | -app:listen() -- To run the server |
52 | | -``` |
53 | | - |
54 | | -3. Create an `app/` directory inside `src/`. This directory will house your routes. |
55 | | -4. To create a route, add a `route.luau` file inside a directory within `app/`. The directory name becomes the base route. |
56 | | - |
57 | | -For example, to create a route at `/`, create `src/app/route.luau`: |
58 | | - |
59 | | -```lua |
60 | | -local Nova = require("@path/to/nova") |
61 | | - |
62 | | -local App = {} |
63 | | - |
64 | | -function App.Get() |
65 | | - return Nova.response.json({ msg = "Hello, Nova" }) |
66 | | -end |
67 | | - |
68 | | -return App |
69 | | -``` |
70 | | - |
71 | | -The module must export properties named after HTTP methods: `Get`, `Post`, `Put`, `Patch`, and `Delete`. You can define them as functions: |
72 | | - |
73 | | -```lua |
74 | | -local App = {} |
75 | | - |
76 | | -App.Get = function() |
77 | | - return Nova.response.json({ msg = "Hello, Nova" }) |
78 | | -end |
79 | | - |
80 | | -return App |
81 | | -``` |
82 | | - |
83 | | -## Core Features |
84 | | - |
85 | | -- **Filesystem Routing:** Routes are automatically mapped to the directory structure of the `app` folder. |
86 | | -- **Pattern Matching:** Native support for dynamic segments using `[params]` syntax. |
87 | | -- **Middleware Pipeline:** Functional middleware chaining for global and route-specific logic. |
88 | | -- **Unified Response Utility:** Standardized handling for JSON and HTML content types. |
89 | | -- **Environment Management:** Automatic `.env` loading and process injection. |
90 | | -- **Integrated Logger:** Colored terminal output for request monitoring and debugging. |
91 | | - |
92 | | -## Routing Conventions |
93 | | - |
94 | | -Nova follows a predictable mapping from the filesystem to the URL path: |
95 | | - |
96 | | -| Path | Filesystem Map | |
97 | | -| :--- | :--- | |
98 | | -| **/** | `src/app/route.luau` | |
99 | | -| **/users** | `src/app/users/route.luau` | |
100 | | -| **/posts/:id** | `src/app/posts/[id]/route.luau` | |
101 | | - |
102 | | -## Middleware Chaining |
103 | | - |
104 | | -Utilize the `chain` helper to apply logic sequentially before a request reaches the final handler: |
105 | | - |
106 | | -```lua |
107 | | --- route.luau |
108 | | -local Nova = require("@path/to/nova") |
109 | | - |
110 | | -local function validate(req, next) |
111 | | - if not req.headers["x-api-key"] then |
112 | | - return Nova.response.json({ error = "Forbidden" }, { status = 403 }) |
113 | | - end |
114 | | - next() |
115 | | -end |
116 | | - |
117 | | -Route.Get = Nova.chain({ validate }, function(req) |
118 | | - return Nova.response.json({ data = "Authorized access" }) |
119 | | -end) |
120 | | -``` |
121 | | - |
122 | | -*More info about middlewares soon.* |
0 commit comments