57 lines
2.9 KiB
Markdown
Executable File
57 lines
2.9 KiB
Markdown
Executable File
# Luxtools Web Application Scaffold
|
|
|
|
Luxtools is a minimal-but-complete scaffold for a retro-styled web application built with the Nim programming language. It demonstrates how to deliver an interactive HTMX front end backed by a Nim HTTP server that compiles down to a single distributable binary.
|
|
|
|
## Why these choices?
|
|
|
|
- **Nim**: Nim's ahead-of-time compilation and small standard library make it ideal for producing a single self-contained binary. Its async HTTP primitives provide great performance with minimal boilerplate.
|
|
- **HTMX**: HTMX keeps the frontend simple by embracing hypermedia. We can ship almost entirely server-rendered HTML snippets, allowing Nim to stay in control without a bulky SPA build step.
|
|
- **TUI.CSS**: This lightweight CSS framework offers a retro terminal aesthetic with zero JavaScript and a tiny footprint—perfect for a nostalgic interface while remaining easy to customize.
|
|
- **Single binary delivery**: HTML templates and the entire `src/static/` tree of vendored assets are embedded at compile time via `staticRead`, so the server ships with everything it needs. The compiled binary serves those resources directly from an in-memory table, while a separate `assets/` directory remains available for user-provided uploads.
|
|
|
|
## Project layout
|
|
|
|
```
|
|
luxtools/
|
|
├── bin/ # Output directory for release binaries
|
|
├── src/
|
|
│ ├── luxtools.nim # Main server entrypoint
|
|
│ ├── static/ # Vendored assets compiled into the binary static table
|
|
│ └── templates/ # HTMX-powered landing page (compiled into the binary)
|
|
├── assets/ # Runtime asset directory served from disk
|
|
├── tests/
|
|
│ └── test_rendering.nim# Lightweight regression tests for HTML helpers
|
|
├── luxtools.nimble # Nimble manifest with build/test tasks
|
|
└── README.md # You're here
|
|
```
|
|
|
|
## Running the app
|
|
|
|
```text
|
|
nimble run
|
|
```
|
|
|
|
This command compiles the server (in debug mode) and starts it at http://127.0.0.1:5000. The console output confirms the address. Open the URL in a browser to see the TUI.CSS interface. The counter widget uses `hx-post` to mutate state on the server, and the clock panel uses `hx-get` with a timed trigger.
|
|
|
|
## Building the single binary
|
|
|
|
```text
|
|
nimble build
|
|
```
|
|
|
|
A release-optimized executable is emitted to `bin/luxtools` (or `bin/luxtools.exe` on Windows). Because the HTML is embedded at compile time, shipping this one file is enough.
|
|
|
|
## Testing
|
|
|
|
```text
|
|
nimble test
|
|
```
|
|
|
|
The test suite checks the generated HTMX markup to catch regressions in the HTML helpers without spinning up the HTTP server.
|
|
|
|
## Next steps (optional)
|
|
|
|
- Add persistence by wiring Nim's database libraries or a lightweight KV store.
|
|
- Serve additional HTMX endpoints (e.g., todo lists, metrics dashboards).
|
|
- Extend the styling by composing more TUI.CSS components or creating custom themes.
|