Thanks so much for this detailed feedback @mwmiller!
This is a really important conceptual hurdle that I need to address better in the docs. Where and how do you think the documentation could be improved to make this client/server boundary clearer?
I haven’t experienced this myself since v0.5.0, but I have some ideas about a possible race condition that might be causing this. I’ll try to implement a fix that should resolve this once and for all.
Yeah, this is a must-have feature and I already have it in my backlog.
Can you elaborate on how this could be improved? Are you thinking bigger/bolder headers, more whitespace, breaking up large sections, or something else entirely?
This should probably be a simple TemplateError saying that the given template variable was not set, along with the line number within the template, right?
Not really - it just means the developer experience isn’t the best at the moment… but we’ll get there!
I wish I knew what to say here. On the one hand the promise is “write Elixir and everything will just work!” The reality of client/server communication is much more complex and nuanced. There are also ethical, privacy and security concerns with making it all look like one big machine image where the constituent nodes are under the control of different agents.
Instead let me tell a story which sort of goes along with the section on confusing error messages. I was trying to pre-parse some of the settings into the proper types. I suddenly got weird errors where Integer.count_digits was having trouble because it received a string. So that looks like I’m hitting a runtime BEAM error, but it shows up in the Javascript error console. It also doesn’t appear to be the code I actually wrote but rather something helping me marshal.
I don’t know why I couldn’t immediately wrap my head around the fact that it was JS running on the client. I suspect it looked “too much like” Elixir which had run on the server and returned the error over the wire instead of a more expected response.
I don’t know how this story might help.
I’m far from a UX expert, but as a reader I need clear delineation between section header and body material. Maybe the header typeface is too small and the body text too large? Maybe some horizontal rules setting off the bits? More indentation cues? Subtle but noticeable color differences?
That would probably work so long as I still get the affected file name or module. It doesn’t seem likely that there would be more than one HOLO sigil per file.
It might also be worth noting that it is fairly difficult to inspect which variables are available while developing. They look like module attributers but they only vivify inside the sigil, so you need to know whence they come in order to poke at them in template/0 before hitting the sigil.
That confusion you experienced is actually a perfect illustration of Hologram working exactly as intended - though I totally understand why it was disorienting!
The whole idea behind Hologram is that it should be completely seamless. You write Elixir everywhere, and the framework handles whether that code runs on the server (as native Elixir/BEAM) or gets transpiled to run on the client (as JavaScript). From your perspective as a developer, it should just be “Elixir code” regardless of where it executes.
So when you used Integer.count_digits/1 in what turned out to be client-side code, Hologram transpiled that to JavaScript and ran it in the browser - which is why you saw the error in the browser console instead of your server logs.
The stack trace situation you encountered is an important feature that I haven’t started working on yet, but it’s definitely on the roadmap. Eventually, you’ll get proper Elixir stack traces that point to your actual source files and line numbers, even for client-side errors. Right now that Elixir source mapping isn’t implemented yet, so you’re seeing the transpiled JavaScript stack traces. You can see this on the official Roadmap - “Client Error Stacktraces - Ensure error messages and stacktraces on the client match those on the server for easier debugging”.
The good news is that the transpiled code is very readable since it’s a one-to-one mapping from your Elixir code - but I know it’s still not ideal for debugging.
Your mental model of “actions probably run on client, commands definitely run on server” is actually pretty solid as a working heuristic! But the real beauty of Hologram is that you shouldn’t need to think about it at all - it should just work seamlessly no matter where the code runs.
I know this kind of architecture can be a little disorienting at first, but once you get the hang of how it works and what’s executed where, it becomes much easier and you really don’t want to go back to the traditional approach of juggling different languages and contexts.
Just to be clear, I was not intentionally using this code from (I believe it is called) IntegerUtils. I was using or attempting to use Integer.parse/1 and it “just showed up”. When I want to count digits, I use logarithms.
I’m sure you’ll be happy to hear that I am already at this point! There are some rough edges, but it’s quite compelling even as is.
