r/nim • u/Niminem93 • 4h ago
Neel 2.0: HTML/JS GUI apps for Nim, rewritten from scratch
https://github.com/Niminem/Neel
Some of you may know Neel. This was my first Nim repository from 2020 when I was first learning it. It was what drove me to move from Python to Nim! It is my child and if you speak ill of it we will have problems (jk).
Neel is a library for making lightweight Electron-like desktop apps: the UI is in HTML/CSS/JS and everything else in Nim.
I just released v2. It is a ground-up rewrite. It is much better- more ergonomic, more capable, more... everything. Especially fun. A lot more fun.
Example, you can mark a Nim proc with {.expose.} pragma and the HTML page can call it as neel.<name>(...) and gets the return value back through a Promise. Register a JS function with neel.expose and Nim calls it as js.<name>(...), or js.wait.<name>(...) when it needs the answer. That's just too f*****g cool man. Neel handles the server, the browser window, the JSON conversion, the errors in between, all that stuff that's a PIA.
The short version of what's new:
- Return values in both directions (1.x had none). Nim exceptions reach JS as
e.name/e.message; JS throws reach Nim asNeelRemoteError. {.expose.}on any top-level proc, in any module. Objects,Option,Table,HashSet, enums, tuples,JsonNode, and default parameter values all convert automatically.- Multiple windows, each addressable from Nim (
openWindow,closeWindow,windows(),requireWindow(id), hooks). - Its own thread-based HTTP/WebSocket server in the spirit of Mummy: one IO thread owns the sockets, a worker pool runs your procs, no async anywhere. Mummy itself is gone.
- Zero dependencies. Standard library only.
- Finds Chrome, Chromium, or Edge and opens them in app mode (no tabs, no address bar); falls back to a tab in the default browser when none is installed.
- Hardened against other websites open in the same browser: per-launch token plus
Host/Origin/Sec-Fetch-Sitechecks, server bound to127.0.0.1only. - Release builds embed the web folder into the binary, so you ship one file.
Verified on macOS, Windows, and Linux (Ubuntu). Requires Nim >= 2.2.12 (older allocators crash intermittently when memory is freed after the owning thread exits, so Neel refuses to compile on them).
A complete app. The page asks for a directory and Nim picks a random entry from it:
import std/[os, random]
import neel
type
MissingDirectoryError = object of CatchableError
EmptyDirectoryError = object of CatchableError
proc filePicker(directory: string): string {.expose.} =
let dir = absolutePath(directory, root = getHomeDir())
if not dirExists(dir):
raise newException(MissingDirectoryError, "no such directory: " & dir)
var names: seq[string]
for _, path in walkDir(dir):
names.add path.extractFilename
if names.len == 0:
raise newException(EmptyDirectoryError, "the directory is empty: " & dir)
var rng = initRand() # exposed procs run on worker threads
rng.sample(names)
startApp()
And the page side (web/main.js, loaded after <script src="/neel.js">):
try {
const name = await neel.filePicker(input.value);
result.textContent = name;
} catch (e) {
error.textContent = e.name + ": " + e.message; // ex: "MissingDirectoryError: no such directory: ..."
}
Calling back into the page from Nim works the same way in reverse:
proc askPage(question: string): string {.expose.} =
let reply = js.wait.answer(question) # blocks until the page answers
"the page answered: " & reply.getStr
proc notify(text: string) {.expose.} =
js.showToast(text) # fire-and-forget
neel.expose(async function answer(question) {
return prompt(question);
});
HOW COOL IS THAT???
Moving on...
nim c -r main.nim for development (assets read from disk, refresh to see changes), nim c -d:release main.nim to ship (assets embedded). Add --app:gui to hide the terminal.
Nothing from 1.x compiles unchanged; the README has the rename table and the guide (docs/GUIDE.md) has every detail: the full type list, error messages, lifecycle, threading model, security, caveats. Three runnable examples in the repo; start with examples/filepicker.
---
Neel started years ago as a port of Python's Eel library (now deprecated), and the 1.x line never really outgrew that: one window, no return values, a block of exposeProcs:, etc. Back in 2023 I rewrote the server with Mummy as the server because of a bunch of async problems but still never addressed some of its shortcomings.
I finally sat down and rewrote the whole thing. The big question was whether to keep an external server library or write one. Mummy had effectively been abandoned (there's a fork, but relying on a fork of an unmaintained dependency for the core of the library didn't sit right), and I'm using Neel for work, so future-proofing it mattered. Writing the server myself also meant Neel controls the threading, the shutdown ordering, and the WebSocket details end to end, which turned out to matter a lot for return values and multiple windows. Mummy is great and the design here is very much borrowed from it: one IO thread, a worker pool, no async. It's just all in the stdlib now, with no deps.
The big thing that ate most of my time was actually the hardening pass. Running all three examples on three OSes, trying to break them, and fixing what broke turned up some fun findings: a refreshed stale tab stealing another window's identity, Edge signing a fresh profile into your Microsoft account and syncing your extensions into the app window, Windows select silently capping you at about 8 windows, an allocator crash that pushed the minimum Nim to 2.2.12, all kinds of stuff. All has been fixed and pinned down with tests.
So this release had a lot of effort put into it. I'm sure you'll find it enjoyable and useful.
I have a few things next on the list: Brave / Opera / Vivaldi discovery (basically any other chromium based browsers), a Webview target (at least for Mac and Linux since Windows is guaranteed to have Edge), custom HTTP routes, and wss:. I will get to them when I can, but issues and PRs welcome of course.
Enjoy!
