Basic Web Development

[seancorfield]

https://clojure-doc.org/articles/tutorials/basic_web_development/

Is this easy to follow?

Are there things that need additional explanation?

Is any part of this confusing?

[Epidiah]

Thank you for this! I just ran though the tutorial this morning and collected my thoughts here as I went along. I consider myself a Clojure beginner, or at the very least near enough a beginner to remember what might have confused me when I was just starting out.

By and large, this was a pretty smooth experience. Just about everything in this post exists because I suspect more feedback is better than just a thumbs-up emoji. That said, 👍!

Hope this is of some help, and I'll happily answer any questions.

Create and set up your project

• A brief explanation of the #' prefix to app-routes and app might be helpful for beginners here. It stands out and it's not clear what purpose it serves.
• A link to https://clojure.org/reference/repl_and_main to explain what is meant by "Clojure's main entry point" would be helpful. As it happens, I was rather confused about clojure.main, the -main function, -M, and -m until this very tutorial prompted me to look all that up.

Add some styling

• I don't know if this is a real issue or not, but the bash commands at the top of this section probably won't work for someone trying this out in Windows. I'm working from a Linux machine at the moment, so I didn't really test that hypothesis, but I remember when I started learning to program I was on Windows and running into bash commands quite a bit in tutorials. It's not a big thing, but just telling someone in that position to "make a resources/public/css directory and create a styles.css file in it" would've helped.
• The CSS didn't quite work as expected. See "My Weird CSS Problem and Final Notes" at the bottom of this post for more details.

Set up your database

• Just want to thank you for the parenthetical here about the namespaces and the maps. That's one of those things that was very confusing when I first stumbled upon it and wasn't quite sure how to search up an explanation on the Internet.

Create some db access functions

• "You can try the code out in the comment form by evaluating the expressions in -- and you should see the same results as the inline comments show." The double hyphen here seems to be a placeholder for something. Or maybe its an em-dash and the sentence is just missing an "it" right before it?

Create your Views

• "Next, we will create the views -- that generate our HTML pages." Only because of the previous comment, I'm wondering if "--" is a placeholder here, or an em-dash. Neither seems necessary, though. The sentence works fine without it.

Set up your routes

• No notes. Perfection.

Run your webapp during development

• I'm not sure if this is within the scope of this tutorial, but changes made to a file are not reflected in the website after the file is saved. The changes need to be evaluated in the repl, I believe. Otherwise, you have to stop and restart the app every time you change something. At least, that's how it seems to be working for me. That might be a source of confusion for a beginner who tries the website out, sees there's something wrong, attempts to fix it, and see no changes even after saving the file. This might be a good place to explain why it won't work like that.

Deploy your webapp

• Thank you for this section!
• Not necessary, but maybe a heads-up that calling clojure -T:build uber might result in downloading some files. Just so no one panics.

My Weird CSS Problem and Final Notes

Oddly, when running the app from Clojure -M -m my-webapp.handler, my browser blocks the styles.css file, saying:

The resource from “http://localhost:3000/css/styles.css” was blocked due to MIME type (“text/html”) mismatch (X-Content-Type-Options: nosniff).
And so I don't see any styling.

But from the uberjar, it delivers the CSS without issue. So the styling is present when run via java. And I'm not entirely sure why the difference.

All in all, a pleasure. I definitely learned some things running through the tutorial, even after having done a few Clojure web tutorials before. Like I said before, if any of this seems helpful, but unclear, I'm eager to clarify.

[seancorfield]

This is excellent feedback! Thank you for taking the time to document all of this. I'll go through it all and incorporate what I can and possibly ask more questions when I do -- probably next weekend.

[seancorfield]

I'll respond to the -- now, though: that's my old grammar school education shining through as I try to write an emdash instead of just a single -. I'll check into what's happening with Cryogen (that turns the Markdown into HTML) and if I can't create proper emdashes in it, I'll try to remember to stop using them!

[seancorfield]

The -- issue is a bug in markdown-clj that Cryogen uses under the hood. I'll talk to the maintainer about that.

[seancorfield]

I believe I've addressed all your feedback -- thank you! -- with the following caveats:

• The -- issue. I've removed a few of them but the remaining ones should because emdash/endash except for the bug in markdown-clj.
• The CSS file content type. I cannot reproduce that: it is always text/css for me, regardless of how I run the webapp.