Constructing a straightforward room-based completely chat application in Nim (the utilize of HTMX)

Constructing a straightforward room-based completely chat application in Nim (the utilize of HTMX)

Right here’s going to be a bit of a peculiar tutorial – reasonably than strolling you thru the natural progression of how one would originate an application, I’ll in its set be explaining the code grade by grade of the present application. Right here’s carried out for 2 reasons: first, it’s more straightforward to write an instructional. 2d, whilst you succesful wish to glimpse the remaining code, you might well skip forward and no longer have to undergo with me as I show things that you just might well be also just already know.

A rapid converse – I utilize the be aware templating and template a bit on this explanation. A template refers to a blueprint in Nim that allows for code substitution. Templating refers to translating our knowledge into HTML, the utilize of Karax’s DSL on this event.

With that out of the fashion, let’s launch! The remaining code may per chance per chance even be chanced on on this Github repo. Right here are just a few screenshots of what we’ll be constructing.

sign in


import std/[strutils, asyncdispatch, sets, hashes, json]
import karax/[karaxdsl, vdom], jester, ws, ws/jester_extra

On the first line we’ve got stdlib imports, and the 2d line has the total exterior libraries we’ll be the utilize of. To set up them, succesful trail

nimble set up karax jester ws
converter toString(x:  VNode):  string = $x
kind Person = object
  name:  string
  socket:  WebSocket
proc hash(x:  Person):  Hash = hash(
var chatrooms = initTable[string, HashSet[User]]()

Now, we’ve got some real code. The first line is a converter. In Nim, converters are automatically ran to convert between kinds if wished. In our case, we are converting a “VNode” to a string whenever it’s miles required. A VNode is nice a DOM part, which is what the Karax DSL makes utilize of to assert HTML. Alternatively, Jester easiest responds with string. With this converter, we can simply resp vnode and delight in it automatically win transformed.

The subsequent few lines simply arrange the tips constructions for this chat application. A user consists of a username, and the websocket much like their computer. We elaborate a hash aim for this model in inform that we can put it to use in a hashset. Then, we elaborate the core in-reminiscence variable that’ll be storing all of our customers and rooms. It’s a map from string, to HashSet[User]. In other phrases, each room name maps to a attach of customers that are related.

template index*(relaxation:  untyped):  untyped =
  buildHtml(html(lang = "en")): 
      meta(charset = "UTF-8", name="viewport", sigh="width=machine-width, preliminary-scale=1")
      link(rel = "stylesheet", href = " up-to-date/css/pico.min.css")
      script(src = "")
      title:  text "Easy Chat"
        ul:  li:  a(href = "/", class="secondary"):  sturdy:  text "Easy Chat"
      predominant(class="container"):  relaxation

Now we win into one of the well-known crucial templating/boilerplate. This snippet builds our “header” and takes within the comfort of the page “relaxation” as input. Taking a nearer glimpse, we can conception that we load a stylesheet (PicoCSS) and HTMX. We then have faith a rapid navbar, all the utilize of the Karax DSL.

Indicate that right here’s a template and no longer a proc. So, something that’s passed in as the comfort argument performs straightforward code substitution. We’ll conception an example of that in a 2d.

proc chatInput():  VNode = buildHtml(input(name="message", id="clearinput", autofocus="", required=""))
proc sendAll(customers:  HashSet[User], msg:  string) =
  for user in customers:  discard user.socket.ship(msg)
template buildMessage*(msg:  untyped):  untyped =
  buildHtml(tdiv(id="sigh", hx-swap-oob="beforeend")): 
    tdiv:  msg

We’ve got some helper procedures right here. chatInput generates our input arena the utilize of the Karax DSL that grabs focal level. It’s additionally required, in inform that the user can’t succesful exclaim mail sending empty messages. sendAll succesful sends a string to the total customers in a room by iterating over them.

buildMessage is one more template that we can utilize to relieve us reuse code for constructing HTML. You’ll additionally look for a entertaining attribute: hx-swap-oob. The documentation for that may per chance per chance even be chanced on right here, but in a nutshell what this does is ready aside the innerHTML of this

proper into a new part, which is the remaining dinky one amongst something matching an id of “sigh”. When you happen to’ve never dilapidated HTMX you might well factor in that right here’s an extraordinarily grotesque manner of doing things, but belief me: it in actuality works.

In other phrases, any time the client sees this div being returned, it appends the sigh into the reside of the DOM part with an id of “sigh”.

  win "/": 
    let html = index: 
      h1:  text "Be half of a room!"
      create(crawl="/chat", `manner`="win"): 
          text "Room"
          input(kind="text", name="room")
          text "Username"
          input(kind="text", name="name")
        input(kind="submit", tag="Be half of")
    resp html

At remaining, some Jester code! Right here’s the index page, the set we will be a half of a room. You’ll look for we utilize our index template create earlier, to relieve us originate the first share of the page, sooner than we insert the comfort of it. This code is rather self explanatory as it’s succesful HTML, but we’re making a create that asks for a room name and a username. Submitting this create will then ship a GET set aside a question to to /chat.

  win "/chat": 
    let html = index: 
      h1:  text @"room"
      tdiv(hx-ws="join:/chat/" & @"room" & "/" & @"name"): 
        create(hx-ws="ship", id="message"):  chatInput()
    resp html

After submitting that create, we reside up on this bit of code. Per the name attributes from the sooner snippet, we can win proper of entry to the username and room the user submitted with @"name" and @"room". You’ll look for the hx-ws attribute right here as successfully, from HTMX. The documentation for it says it’s going to are trying and launch a websocket connection to the URL it’s miles given.

Though-provoking on, we conception a paragraph with the id “sigh”. Right here’s the set the sooner snippet may per chance per chance even be dilapidated to append HTML inside of that tag. Within this div, now we delight in a create with the attribute hx-ws again, easiest this time it’s miles determined to “ship”. Wanting at the documentation from earlier shows that any time this create is submitted, a JSON response will seemingly be ship to the closest opened websocket. In other phrases, submitting this create will ship something cherish

{"message":  "right here is my message!"}

over the websocket connection to the server.

  win "/chat/@room/@name": 
    var ws = are waiting for newWebSocket(set aside a question to)
    var user = Person(name:  @"name", socket:  ws)

Right here’s the set we take care of the websocket connection. We utilize treeform’s library to have faith a new websocket, after which we have faith a new Person that corresponds to that websocket. The following code is a bit tricky, as it makes utilize of the helpers we outlined earlier.

    are trying: 
      chatrooms.mgetOrPut(@"room", initHashSet[User]()).incl(user)
      let joined = buildMessage: 
        italic:  text
        italic:  text " has joined the room"
      while user.socket.readyState == Delivery: 
        let sentMessage = (are waiting for user.socket.receiveStrPacket()).parseJson["message"]
        discard user.socket.ship(chatInput())
        let acknowledge = buildMessage: 
          courageous:  text
          text ": " & sentMessage.getStr()

Oh boy, right here we trudge. Neatly, the entirety is wrapped in a are trying block first of all. First, we have faith a new HashSet in that desk we outlined earlier if it didn’t already exist. We additionally add the user to the HashSet that holds the customers for the given room. The following lines generate the message that’s sent on be a half of. We utilize the buildMessage template to make certain that it’s miles appended to the reside of the predominant sigh. Then, we utilize the sendAll proc to make certain that it’s miles sent to each user related to that room.

The following while loop easiest runs while the user is related (readyState == Delivery). Be unsleeping, we are the utilize of Nim’s async module, so the loop is non-blocking. We exclaim a message to be sent over websockets, parse the JSON, and take hang of the “message” key. I talked concerning the JSON structure a bit earlier.

The following line is peculiar – we ship the chatInput attend to the client we succesful got a message from. When you happen to be unsleeping from earlier, something that’s sent over the websocket may per chance per chance well delight in it’s id attribute checked, and the sigh will affect the DOM. On this case, the part that’s sent over will change the input tag that the user has on their machine. Right here’s carried out for 2 reasons:

  1. The input tag that the user has on their machine has some text in it (the message that they sent). By sending over a blank one, we clear the message.
  2. Resulting from the autofocus attribute, we regain focal level of the text input.

In most cases, you’d potentially clear the input with Javascript. Since we’re the utilize of HTMX nonetheless, right here is the urged manner of doing things. Additionally, factor in that you just needed to filter the messages (as an illustration, to envision for slurs). On this model, you’d be ready to rapidly and without assert clear the input and consist of a message in conjunction with the cleared input telling the user why the message wasn’t popular.

After that a dinky prolonged explanation, we originate the message itself in Karax’s DSL, the utilize of our buildMessage helper. Then, we ship the message to the whole related customers.

    aside from: 
      let left = buildMessage: 
        italic:  text
        italic:  text " has left the room"
    resp ""

Be unsleeping how all that code modified into wrapped in a are trying block? Right here’s the matching aside from. An exception on this code will in most cases be thrown if there modified into some create of error with the websocket. When you happen to wished to be more right you might well salvage the right exceptions, but as right here is SIMPLE chat I didn’t anxiousness.

If there’s an error with the websocket, we take hang of that to mean that the user has disconnected. We salvage them from the chat room that they had been in. Then, we originate a message to describe that the user has left the room. At remaining, we ship that to the total remaining possibilities within the room! The remaining resp is there to verify that that Jester has something to cease the reference to for the user that left.


And that’s it! Round 70 lines of code to originate a room based completely chat the utilize of nothing but HTMX and Jester! The right share of this code? You don’t deserve to know or impress Javascript to work with this stack, it’s inconceivable. The code ground for bugs on the client side is rather much 0, but on the server side it does trudge up a bit with the hx-swap common sense. Aloof, a minimal of the common sense is easiest in one codebase.

This stack isn’t for every person, and I’m no longer claiming that you just might well be originate each create of application with it. I judge about it to be very worthy for what it’s going to make without heaps of of code. I hope that this modified into informational and reliable!

Be half of the pack! Be half of 8000+ others registered customers, and win chat, invent groups, submit updates and invent website visitors around the arena!



Hey! look, i give tutorials to all my users and i help them!