Between Two Parens

Rich Comment Blocks

2024-11-11T22:08:33Z

The three main types of comments in Clojure are

The last one, the Rich Comment, is a pretty cool feature of Clojure.

Comment

The first type of comment is a literal comment

; I'm a comment

Anything that follows the ; is ignored by Clojure until the end of the line. A common use for a comment is to add human readable documentation to your code to help the people reading our code understand it. We can also comment out blocks of code which we don't want our program to run.

Discard Comment

The second type of comment is a discard comment

(-> 5 inc inc inc)     ; 8

(-> 5 inc #_ inc inc)  ; 7

The #_ will comment out the form directly behind it. In the above, the code commented out is the second inc.

I actually ignored this tool for an embarasignly long time, but it's wildly useful and actually makes coding faster!

At a high level, what makes the discard comment great is that it doesn't return a value, they nest and you can insert it into the middle of a line of Clojure code and it only comments the form directly behind it.

Additionally, if you're commenting out an entire block of code you only have to add the discard to the top level of the form and the entire form will be commented. This means the formatting of the code block won't be affected and you have very little code to remove.

Here's an example of nesting:

(-> 5 #_ inc #_ inc inc) ; you could discard each form in turn
(-> 5 #_ #_ inc inc inc) ; or you could stack them

Here are some examples of where you might find the discard comment useful:

(or #_ (int? 2) (nil? "Thomas"))

(let [my-number 5
      #_ #_ another-number 13]
  ;...
  )

{#_ #_ :name "Between Two Parens" :host "Thomas"}

The second take away is that you don't have to add spaces after the discard comment:

;; these all produce the same result
(-> 5 #_ inc #_ inc inc) ; space
(-> 5 #_inc #_inc inc)   ; no space

(-> 5 #_ #_ inc inc inc) ; space
(-> 5 #_#_inc inc inc)   ; no space

The difference between adding the space or removing the space is which one you find more readable.

Rich Comment

Finally, we have the comment macro which is more affectionatley known as a Rich Comment Block:

(comment
  ; everything in here is ignored...returns nil
  )

The first time I heard of a Rich Comment was in Stuart Halloway's excellent talk Running With Scissors where he notes:

Yet, even after watching Running With Scissors the use of the Rich Comment hadn't started to click yet. Two more things would need to happen: The first, I would witness REPL Driven Development used in person by David Nolen. The second, I would start to use REPL Driven Development in my own workflow. When I did these things, I was able to better see the benefits of the comment macro as

documentation
a save point
code setup
improved code exploration
preservation of syntax highlighting

With that, let's review a few examples of the Rich Comment from real life Clojure codebases.

The first example illusrates the documentation and save point ideas.

(comment

(println (sh "ls" "-l"))
(println (sh "ls" "-l" "/no-such-thing"))
(println (sh "sed" "s/[aeiou]/oo/g" :in "hello there\n"))
(println (sh "sed" "s/[aeiou]/oo/g" :in (java.io.StringReader. "hello there\n")))
; ...
)

The above comes from the clojure codebase itself and is a code example of how to use sh. For me, the value is that we have an example of how to use sh (documentation) and we have some code ready for us to run through our REPL (a save point). This idea of having a save point becomes more powerful in the next example:

(comment
  (do
   (require '[my.app.db :as app.db])
   (require '[my.app.cart :as cart])
   (def db (app.db/connection!)))

  (cart/add db {:item-name "iPhone"})

The above builds on the idea of having a save point and layers on some code setup helpers. What the above does is add in a few lines of code which, when run, will provide us with a db connection. Through this, I can quickly begin interacting with my app's database code and building out features.

Of course, there are other types of setup code that you may want. For example, you might be working on a pure function which is just going to transform some data. In this case, we might setup a comment like this:

(comment

  (def xs #{{:a 11 :b 1  :c 1 :d 4}
            {:a 2  :b 12 :c 2 :d 6}
            {:a 3  :b 3  :c 3 :d 8 :f 42}})

  (def ys #{{:a 11 :b 11 :c 11 :e 5}
            {:a 12 :b 11 :c 12 :e 3}
            {:a 3  :b 3  :c 3  :e 7}})

  (join xs ys))

The above is the example Stuart provided in his talk which provides us with some sample data allowing us to immediately begin using our functions to transform said data.

Conclusion

These are just a few examples of how to use a Rich Comment Block. The most interesting part of the Rich Comment Block for me is that it's a tangible example of the pragmatism of Clojure. In this case, the comment macro provides an additional mechanism for speeding up my workflow and making our code more maintainable overall because of the improved documentation and context we get from these comments.

What are the Clojure Tools?

2024-11-11T22:08:33Z

The Clojure Tools are a group of convenience tools which currently consist of:

Clojure CLI
tools.build

The Clojure Tools. were designed to answer some of the following questions:

How do I install Clojure? (Clojure CLI)
How do I run a Clojure program? (Clojure CLI)
How do I manage Clojure packages (dependencies)? (Clojure CLI)
How do I configure a Clojure project? (Clojure CLI)
How do I build Clojure for production? (tools.build)

The rest of this post will dig into each of these tools.

Clojure CLI

The Clojure CLI is a CLI program. Here is what it looks like to use the Clojure CLI and some of the things it can do:

Run a Clojure repl

clj

Run a Clojure program

clj -M -m your-clojure-program

manage Clojure dependencies

clj -Sdeps '{:deps {bidi/bidi {:mvn/version "2.1.6"}}}'

Like all Clojure programs, the Clojure CLI is built on a few libraries:

clj/clojure - a bash script
tools.deps a clojure library (commonly referred to as deps)
deps.edn - an edn file with a specific structure

The following sections will provide overviews of each of the above tools.

The Clojure CLI is invoked by calling either clj or clojure shell commands:

# clj
clj -M -m your-clojure-program

# clojure
clojure -M -m your-clojure-program

Under the hood, clj actually calls clojure. The difference is that clj wraps the clojure command with a tool called rlwrap. rlwrap improves the developer experience by making it easier for you, a human, to type in the terminal while you're running your Clojure REPL. However, even though it's easier for you to type, rlwrap can make it hard to compose the clj command with other tools. As a result, it's a common practice to use clojure in production/ci environments . Additionally, not all environments have access to rlwrap so it's another dependency you have to install.

Okay, so they do the same thing. What do they do? clj/clojure has one job: run Clojure programs against a classpath.

The next sections will outline the tools that make up the Clojure CLI tool.

clj/clojure

If you dig into the clj/clojure is just a bash script which ultimatley calls a command like this:

java [java-opt*] -cp classpath clojure.main [init-opt*] [main-opt] [arg*]

Thus, the Clojure CLI tool makes it easier to run Clojure programs. It saves you having to type out a gnarly Java command and make it work on different environments (windows, linux, mac etc). However, it orchestrates the building of the classpath by calling out to tools.deps.

tools.deps

tools.deps is a Clojure libary responsible for managing your dependencies. It does the following things:

reads in dependencies from a deps.edn file
resolves the dependencies and their transitive dependencies
builds a classpath

What's interesting about this program is that it's just a Clojure library. This means that you can use it outside of the Clojure CLI.

The other thing that makes tools.deps great is that it's a small and focused library. Why this is great is that if something goes wrong it's easy to read and learn the library in a short period of time.

deps.edn

deps.edn is just an edn file where you configure your project and specify project dependencies. You can think of it like Clojure's version of package.json. The deps.edn file is a Clojure map with a specific structure. Here's an example of some of the properties of a deps.edn file:

{:deps    {...}
 :paths   [...]
 :aliases {...}}

As you can see, we use the keywords :deps, :paths and :aliases and more to start to describe your project and the dependencies it requires.

As we noted above, deps.edn is read in when you run clj/clojure and tells clj/clojure which dependencies are requires to run your project.

Tools.Build

tools.build is a Clojure library with functions for building clojure projects. For example, build a jar or uberjar.

The way you would use tools.build is by writing a separate program inside your app which knows how to build your app. The convention is to create a build.clj file in the root of your project. Import tools.build and use the functions provides by tools.build to build your program.

The 3 main types of Clojure programs one might build into 3 sub categories:

A tool
A library
An app

When you run your build.clj file, you will use Clojure CLI's -T switch. The -T switch is meant to run general clojure programs via the Clojure CLI and since build.clj is a separate program, distinct form the app you are writing, you would run it via the -T switch.

You would use -T for Clojure programs that you want to run as a "tool". For example, deps-new is a Clojure library which creates new Clojure projects based on a template you provide. This is a great example of a Clojure project which is built to be a "tool".

I don't want to go into more detail about -T now because that means we would have to dive into other Clojure CLI switches like -X and -M. That's for another post. On to the Installer!

Installer

The "Clojure CLI Installer" is a fancy way of referring to the brew tap used to install Clojure on mac and linux machines. As of February 2020, Clojure started maintaining their own brew tap. Thus, if you installed the Clojure CLI via

brew install clojure

you will likely want to uninstall clojure and install the following:

brew install clojure/tools/clojure

In all likelihood, you would probably be fine with brew install clojure as it will recieve updates. However, while brew install clojure will still see some love, it won't be as active as the clojure/tools/clojure tap.

clj v lein v boot

This section will provide a quick comparison of clj, lein and boot.

Firstly, all of the above tools are more or less addressing the same problems in their own way. Your job is to choose the one you like best.

If you're curious which to choose, my answer is the Clojure CLI. The reason I like the Clojure CLI is because the tool is simple. You can read through clj and tools.deps in an afternoon and understand what they are doing. The same (subjectively of course) cannot be said for lein or boot. I will note that Clojure CLI's API is not straightforward and can be confusing.

Secondly, the Clojure Tools promote libraries over frameworks. This is important when working with a language like Clojure because it really does reward you for breaking down your thinking.

Finally, the Clojure community is really leaning into building tools for Clojure CLI. For example, where lein used to have significantly more functionality, the community has built a ton of incredible tools that will cover many of your essential requirements.

Footnotes

In earlier versions of this blog post I referred to the Clojure CLI as Clojure Tools. The reason I now refer to them as the "Clojure CLI" is because on August 21, 2020 it was announced in Clojurians (The official Clojure Slack Org) that cognitect released a free set of tools called Cognitect Dev Tools. Thus, I made the change to be very clear that there is a difference.
Back
Of course, production scripts are not the only times you would want to use the clojure command. Other times include when you are combining it with other tools e.g. emacs. In general, if you are finding the clj command is causing some headaches when composing tools, give clojure a try. Thanks, sogaiu for the tip!
Back
To clarify the "monorepo" comment: Choosing a sane structure for your monorepo is important to making this work. I have a personal project which has 4 or 5 sub-projects and I have not run into any issues as of yet. I would eventually love to write about my approach, but until then checkout Sean Corfield's Blog Post about Clojure Monorepo using Clojure CLI Tools.
Back

Manage your Java JDKs

2024-11-11T22:08:33Z

Pro tip for anyone working with any programming language: Find a clean and easy way to switch versions of your programming language of choice.

All it takes is a CI environment running a different version of your programming language and the world goes Pete Tong.

My approach is to use a language version manager. If you're using JavaScript, nvm is a great option, Ruby has rvm and for Clojure developers we have tools.deps for managing versions of Clojure and jEnv for managing our JDKs.

Why Version Management Tools

Version management tools allow us to quickly and easily manage (add, switch, remove et al.) the version of our programming languages. This enables us to easily test our code against different languages. Example scenarios where I've had to switch language versions:

Debugging CI environments
Resolving "works on my machine" issues
Regression testing an app or library against an older version of a language
Switching between multiple projects with different language version requirements

The need to do this exists with all programming languages. Some languages are easier to do this with than others. For example, with Clojure you don't need a tool, you just use tools.deps to specify the version of the language you want to use. With Java, it's more complicated so I use a tool called jEnv.

jEnv is a tool that allows you to manage your Java JDK installations. It you switch between versions of the JDK. One thing to note is that this tool does not allow you to install a JDK. You have to do this separatley. Further, while it's straightforward to setup jEnv, there are some gotchas which is why i'm writing this guide.

Install jEnv

The first thing we have to do is install jEnv.

brew install jenv

and now let's do a sanity check to see if it's installed correctly. Run:

jenv doctor

and if the above worked you should see something like this:

[ERROR]	Java binary in path is not in the jenv shims.
[ERROR]	Please check your path, or try using /path/to/java/home # ...
[ERROR]	Jenv is not loaded in your zsh
[ERROR]	To fix : cat eval "$(jenv init -)" >> /Users/# ...

Configure jEnv

Assuming the above worked, we can now configure jEnv. The next step is to add jEnv to our PATH by updating our configuration file.

To do this, you need to know which shell you're running. Type the following into your terminal to figure out the shell you're running:

echo $0

If you are using bash, the above will print out -bash and if you're using zsh the above will print out -zsh. Once you discover which shell you are using, please choose the associated code block below and run the code inside of it line by line:

zsh shell

echo 'export PATH="$HOME/.jenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(jenv init -)"' >> ~/.zshrc

bash shell

echo 'export PATH="$HOME/.jenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(jenv init -)"' >> ~/.bashrc

Now we can once again run a sanity check:

jenv doctor

Which will return something like this:

[OK]	No JAVA_HOME set
[ERROR]	Java binary in path is not in the jenv shims.
[ERROR]	Please check your path, or try using /path/to/java/home #...
[OK]	Jenv is correctly loaded

As you can see, we now have two less errors. We're making progress! From here, we want to run the following:

jenv enable-plugin export
exec $SHELL -l

and now running jenv doctor returns this:

[OK]	JAVA_HOME variable probably set by jenv PROMPT
[ERROR]	Java binary in path is not in the jenv shims.
[ERROR]	Please check your path, or try using /path/to/java/home #...
[OK]	Jenv is correctly loaded

At this point, jEnv is setup and the last item on our list is to install a Java JDK. If you don't have one installed checkout Adoptium

Add a JDK to jEnv

Not sure if you have a Java JDK installed? No worries, we'll find out together!

Run the following command in your terminal to see which Java JDKs we have installed.

/usr/libexec/java_home -V

and that will print something like this:

Matching Java Virtual Machines (2):
    21.0.3 (arm64) "Eclipse Adoptium" - "OpenJDK 21.0.3" /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home
    17.0.11 (arm64) "Eclipse Adoptium" - "OpenJDK 17.0.11" /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home
/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home

If you see something like the above, it means you have at least one Java JDK installed and you can continue on with this section.

Now we can go ahead and add JDK's to jEnv so it can manage them for us. Run the following command

jenv add /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home

When you run the above, you will see something like this returned:

temurin64-21.0.3 added
21.0.3 added
21.0 added
21 added

As a sanity check, we can run jenv versions to see if jEnv knows about our JDK:

* system (set by /Users/username/.jenv/version)
  21
  21.0
  21.0.3
  temurin64-21.0.3

Great, but remember how I have two JDK's installed? The above indicates that only one of them is being managed by jEnv. This means I have to run through the above step again to have jEnv know about the other version of the JDK I have installed. So, let's repeat those steps:

jenv add /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home

again we get our success output

temurin64-17.0.11 added
17.0.11 added
17.0 added
17 added

and when we check versions available now by running jenv versions we have both 11 and 13 available to us:

* system (set by /Users/username/.jenv/version)
  17
  17.0
  17.0.11
  21
  21.0
  21.0.3
  temurin64-17.0.11
  temurin64-21.0.3

Set a JDK version via jEnv

As a final step, we want to actualy set a JDK to be the one we use. You have two options for this: jenv local and jenv global.

jenv local is going to set your JDK of choice for your current terminal session. jenv global is going to set your chosen JDK as the default for all terminal sessions. For now, let's set a global version. In my case, i'm going to set my jenv global to AdoptOpenJDK 11 like this:

jenv global 21.0.3

Now, in order for the above to take effect, we have to open a new terminal window. Once you open a new terminal window run the following command to be sure our specified version of Java was set:

java -version

and you should see something like this:

openjdk 21.0.3 2024-04-16 LTS
OpenJDK Runtime Environment Temurin-21.0.3+9 (build 21.0.3+9-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.3+9 (build 21.0.3+9-LTS, mixed mode)

That's everything involved in setting a global version of JDK through jEnv.

Uninstalling Jenv

If for any reason you feel like something went wrong while installing jenv, or maybe you just don't like jEnv and you want to cleanup your environment the following steps will help you remove it.

brew uninstall jenv

Remove the .jenv directory

rm -rf ~/.jenv

remove the PATH and init script we added to our shell (either bash or zsh)

That's everything involved in setting up and working with Jenv. I hoped this helped.

Reagent & Hiccup

2024-11-11T22:08:33Z

I'm writing this post because hiccup in the context of Reagent confused me and I wanted to work through some of the confusion.

Things that confused me: I apparently don't need to import a library, modify my build tools or do anything and I just get to write hiccup for free? How is this possible? Also, what is hiccup and is it the same everywhere?

In React (JavaScript) you primarily write your HTML markup with JSX. In Reagent (a ClojureScript wrapper around React) we write our HTML markup with something called hiccup.

Here is a React hello world written in JS uxing jsx:

ReactDOM.render(
  <h1 className="welcome">Hello, world!</h1>, // <-- JSX
  document.getElementById('root')
);

Here is the same React hello world written in Reagent using hiccup:

(reagent.dom/render
  [:h1 {:class "welcome"} "Hello, world!"] ; <-- Hiccup
  (.. js/document (getElementById  "root")))

Let's pull the JSX and hiccup out so we can see them clearly:

// JSX
<h1 className="welcome">Hello, world!</h1>


// hiccup
[:h1 {:class "welcome"} "Hello, world!"]

For fun, here is some more hiccup:

[:ul {:class "list"}
  [:li {:class "list-item"} "Item 1"]
  [:li {:class "list-item"} "Item 2"]
  [:li {:class "list-item"} "Item 3"]]

The rest of this post is going to dig into the questions asked in the introductory paragraph.

Reagent Hiccup

Let's return to the original reagent code snippet we started with:

(reagent.dom/render
  [:h1 {:class "welcome"} "Hello, world!"] ; <-- hiccup
  (.. js/document (getElementById  "root")))

On line 2 we have a Clojure vector. Don't overthink it. It's just a vector. However, because of the order and type of the arguments, it becomes hiccup.

To be considered valid Reagent Hiccup, the vector you pass to Reagent needs to take on one of the following shapes:

[tag]

; => [:h1]

[tag attributes]

; => [:h1 {:class "welcome"}]

[tag children]

; => [:h1 "Hello world!"]

[tag attributes children]

; => [:h1 {:class "welcome"} "Hello world!"]

Here is another way to break it down:

tag
- A keyword (:h1) or symbol (hi)
attributes
- A map {:class "welcome"}
children
- A string ("Hello world!"), vector ([:p "hi"]) or symbol (hi)

How does Reagent know what do with hiccup? The reagent.dom/render accepts either Reagent Hiccup or a React Element as the first argument. So by providing a vector, Reagent automatically treats it like Reagent Hiccup.

Thus, if we were to pass something that's not actually Reagent Hiccup, Reagent is kind enough to throw a JavaScript assertion error in the browser console letting us know what went wrong.

Okay, so Reagent can just accept hiccup. How does Reagent understand Hiccup and know what to do with it? We didn't import a library or add a plugin to our build tools?

The answer is that Reagent comes with a Hiccup compiler built-in which converts Reagent's hiccup to React Elements.

Reagent Hiccup to React Element

The process begins by Reagent passing the component given to reagent.dom/render to a function called create-class.

create-class has other jobs aside from handling Hiccup, but one of it's jobs is to compile Reagent Hiccup to React.createElement calls. This step is handled by the as-element function.

as-element accepts Reagent Hiccup like this:

[:h1 {:class "welcome"} "Hello, world!"]

Compiles it to React.createElement function calls like this:

React.createElement(
  "h1",
  {className: 'welcome'},
  "Hello, world!"
);

The above is given to React which actually runs the React.createElement calls turning them into React Elements like this:

{
  type: "h1",
  props: {
    className: 'greeting',
    children: "Hello, world!"
  }
};

which ultimatley gets turned into HTML

<h1 class="welcome">Hello, world!</h1>

Understanding that everything is turned into React.createElement calls you might be asking, "Could we just use React.createElement and not use Reagent Hiccup?". The answer? Yup!

Reagent Without Hiccup

Similar to React and JSX, you can use plain old React.createElement to create Reagent Components. For example, where we wrote the original example as:

(reagent.dom/render
  [:h1 {:class "welcome"} "Hello, world!"]
  (.. js/document (getElementById  "root")))

we could also use reagent.core/create-element to write a Reagent component like this:

(reagent.dom/render
  (reagent.core/create-element
    "h1"
    #js{:className "welcome"}
    "Hello, world!")
  (.. js/document (getElementById  "root")))

Thus, the following are equivalent

; hiccup
[:h1 {:class "welcome"} "Hello, world!"]

; reagent function
(reagent.core/create-element
  "h1"
  #js{:className "welcome"}
  "Hello, world!")

Understanding this, are there any reasons to use reagent.core/create-element over Reagent Hiccup?

Why Reagent Hiccup?

From a technical perspective, you can argue that there is less work being done if you don't use hiccup because you don't have to convert hiccup to createElement calls. However, i'm not sure this optimization would be worth it. Especially because you could just change the implementation of hiccup to be run at compile time and see the performance improvements and still have the advantage of writing your components in hiccup.

From a developer experience perspective, you might suggest that using reagent.core/create-element over hiccup initially feels easier to teach new developers how to create components in React/Reagent. However, this is subjective and I could argue that hiccup is far friendlier and because of its uniquity is a better tool to rely on.

Some more reasons we use Hiccup in Reagent is similar to the reasons for using JSX in React.

Separation of concerns: Separate by component vs. technology
Accessibility: easier to read and write than React.createElement
Expressivity: it's a Clojure data structure, so we have the full power of Clojure

The second point, Accessibility, is particularly interesting. One of the things I mean by this is that because Hiccup is a popular DSL in Clojure land, and not specific to Reagent, it can be quickly be adopted by developers already familiar with Hiccup.

Hiccup and Clojure

As I mentioned at the top, there are many flavours of hiccup. hiccup is not a Reagent thing, but a DSL which was adapted from a server-side tool called Hiccup.

hiccup was introduced by James Reeves and has become a standard DSL for Clojure developers looking to represent HTML in Clojure. This means that there are many 3rd party libraries which allow you to write Hiccup in your app even if you aren't using Reagent. For example, the following are all examples of popular Hiccup libraries.

And I think this is the beginning of some of the confusion when it comes to hiccup and Reagent.

When one starts to learn ClojureScript, they often start with Clojure. The Clojure guides, references and libraries are generally oriented towards Clojure. While this is understanable, it can create a challenge when trying to figure out how to write HTML in Clojure.

My story was that I started with Clojure building a little MPA with hiccup. I found my library of choice and made stuff appear on the screen by calling the hiccup library I chose. Then I tried to make the same thing happen in Reagent and noticed that I didn't need a library or to call to anything and it all just worked. I eventually learned what was happening, hence this post, but it was irritating at first to not get what was really going on.

Conclusion

The overarching point is that hiccup is a common way of writing HTML is Clojure. Unlike JSX, which for a long while was a React only thing, Hiccup is not specific to Reagent/React. So, this point is meant to provide the context.

Want to learn more about hiccup? Tonsky's article on hiccup is pretty great.

Clojure Text Editors

2024-11-11T22:08:33Z

One of the most common beginner Clojure/Script questions I see is, "which text editor should I use?". I can relate to this question because it's the same one I had when I started. Most of the answers I found led me to using emacs. So, I started to learn Clojure and emacs at the same time. This was a bad decision becuase it was simply too many things to learn at once.

What I should have done is stuck with the editor that I knew best and focused on learning Clojure.

My goal with this post to provide an outline of the popular editors and some insight into which editor I feel will suit developers at different levels of experience.

Clojure Text Editors

Let's start by introducing the top Text Editors for Clojure(Script) development based on the 2023 State of Clojure Survey.

For those who've been in the programming game for a little while, the above list is probably unsurprising. For those new to programming, the above list can feel overwhelming.

The best thing to know about the above list: they are all good choices and it's going to be your personal preferences which determines which one is going to be the best for your workflow. Additionally, You DO NOT need to use Emacs or IntelliJ to learn or become excellent/get the most out of Clojure.

Which Text Editor to Use

In general, there are two groups of developers:

A. "Experienced" developers (hobbyist/professionals)
B. New developers

If you're A, stick with the editor your currently using. If you're B, try Sublime or VS Code.

A Text Editor is a developer's primary tool. We spend most of our work life inside of them. Given time, you're going to develop an opinion about what you like and don't like about your text editor of choice. For example, I want to know that I'm productive in whichever Text Editor I'm using so I want to know that it's fast and that I can customize it when I need to so I can adapt it to my changing development requirements. So, I want it to start fast, I want to be able to quickly and easily setup my editor on other machines, I don't want to see lag when I'm typing, searching large codebases or opening files. When I want to customize something with the editor, I want to be in control where it makes sense.

All of this is to say that these are my preferences that I have built through years of experimentation and self-analysis. If you have been developing for a while, you will have likely gone through a similar process. But let's go back to the original question of "which text editor to choose?".

As I said earlier, if you're an experienced developer, go with the editor you know. If you are a new programmer and don't have deep ties to any particular editor, choose Sublime or VS Code. The reason for this recommendation is because these editors are easy to use, work on all operating systems, have active and easy to access communities and support all the modern Clojure tooling one could ever want.

Im comparison, if you choose an editor like Emacs, Vim, or Intellij you are going to spend more time learning and configuring the editors than learning Clojure. You can always try these editors when you feel more accomplished with Clojure and want to optimize your workflow. But at least when you get to this point you will have a frame of reference.

Knowing this, lets move onto how I setup Atom for my development workflow.

My Text Editor Setup

I use nvim as my daily text editor for all development because it's fast, customizable and I can control how much or little I want nvim to do. The problem with Vim is that it's not friendly to people new to software development. For those interested in my nvim setup you can see my Dotfiles.

Conclusion

Programming communities always form around text editors. No matter which programming language you choose there are always going to be a large number of decisions to make. The important thing to remember is that in the beginning it's often easier if you focus on learning one thing at a time. When it comes to programming, learn the language first and choose tools which allow you to focus on learning your language of choice. Learning new things is hard enough, so be good to yourself in your learning journey and try not to obsess over all the details or aligning to anyone's perception of the ideal programmer.

Deploy ClojureScript on Nginx

2024-11-11T22:08:33Z

My first blog post outlined how to deploy a static ClojureScript website to Github Pages. This is an excellent choice for personal websites, or an open source project's documentation because you get free hosting infrastructure with relatively little effort. Having said this, what happens if you can't use static hosting providers like Github Pages or Netlify? What if you need to control more of the hosting service? This post will show you how to deploy your ClojureScript site on a webserver you control.

The Deploy Process

In order to make our site available to the internet we need a physical webserver and a software webserver. Once we have these, we just have to:

Store your website's artifacts (html, css and js) on a physical server
Teach your software webserver where those files live

In order to do the above, we need to perform the following steps:

Build your website's production artifacts
Move your website's production artifacts to a physical webserver
Configure your software webserver to deliver your website's artifacts to users

These steps are the same whether you are writing JavaScript, ClojureScript, Reason etc.

We can illustrate the whole process on your computer right now by:

Using your as your physical server
Using Nginx as our software server
Using ClojureScript for our static website
Using docker to make the deploy consistent and predictable

Housekeeping

If you are going to follow along with this post please make sure you have the following tools installed:

Create App

Start by creating a basic ClojureScript app. The easiest way to do this is by following the templates getting started guide.

Once the above is complete you should have a project that looks like this:

.
├── README.md
├── deps.edn
├── dev.cljs.edn
├── resources
│   └── public
│       ├── index.html
│       └── style.css
├── src
│   └── demo_clojurescript_nginx
│       └── demo_clojurescript_nginx.cljs
└── test
    └── demo_clojurescript_nginx
        └── demo_clojurescript_nginx_test.cljs

Sanity Check Webserver

I always start with a sanity check. A sanity check is us setting a baseline to make sure things are working. If you were decorating a tree, this step would be us making sure the lightbulbs are working before we decorate the tree.

We're going to verify that we can use docker to pull and run an Nginx container locally. To begin, pull an nginx docker image into your local filesystem:

docker pull nginx

We can verify that the image was successfully pulled in by running the following command

docker images

and if all went well we should see an Nginx image in your local filesystem like:

REPOSITORY  TAG    IMAGE ID     CREATED     SIZE
nginx       latest 540a289bab6c 3 days ago  126MB

If that went well, we can try to run our nginx docker container

docker run --name demo-clojurescript-nginx -p 80:80 -d nginx

and once again we will verify that the container is running

docker ps -a

and you should see something like

CONTAINER ID  IMAGE  COMMAND                  CREATED        STATUS
9118c08ed0a6  nginx  "nginx -g 'daemon of…"   6 seconds ago  Up 4 seconds

and now you should be able to visit your docker container at http://localhost:80.

If the above is working we can move onto the next step which is deploying our app. The reason I'm manually going through these steps is so that we have a clear understanding of what we'll eventually automate.

Before we continue, make sure you stop your Nginx docker container and remove it like so:

docker stop demo-clojurescript-nginx \
&& docker rm demo-clojurescript-nginx

and let's start it again except this time we will start it on port 4001.

docker run --name demo-clojurescript-nginx -p 4001:4001 -d nginx

Build Production Artifacts

This section is about building production artifacts. To clear things up, when I say artifact I mean the code that will be run by our webserver. In the case of a web development project, the artifact will be the minified and dead code eliminated JavaScript produced by the ClojureScript compiler.

To create this artifact we have to tell the ClojureScript compiler to build it for us. We do this with the following command:

clojure -M:prod

After the above command is run we can verify that we have a production artifact by looking into the out directory and finding a file called dev-main.js

out
├── cljs
│   ├── core
│   ├── core.cljs
│   └── core.js
├── dev-main.js
...more stuff

If that has worked, we can move to the next step: putting our production artifacts on the physical webserver (docker container).

Move Production Artifacts to Webserver

This step is about creating a place for our production artifacts to live. To do this, we are going to manually go inside our nginx container and create the folder structure.

docker exec -it demo-clojurescript-nginx bash

and how create the folder like this:

mkdir -p var/www/app/cljs-out

and then exit the docker container. From here we can move the production artifacts from our local machine to the docker container.

# move the js artifact
docker cp out/dev-main.js demo-clojurescript-nginx:var/www/app/cljs-out/
# move the css artifact
docker cp resources/public/style.css demo-clojurescript-nginx:var/www/app/style.css
# move the html artifact
docker cp resources/public/index.html demo-clojurescript-nginx:var/www/app/index.html

From here, we just have to teach our webserver how to serve these files.

Teach Webserver to Serve Artifacts

At this point we just have to configure our Nginx server to know where our production artifacts live. To do this, we have to remove the default Nginx configuration file and replace it with a new one.

Start by execing into the Nginx docker container:

docker exec -it demo-clojurescript-nginx bash

Remove the old configuration file:

rm /etc/nginx/nginx.conf

Then exit out of the docker container. At this point, we want to create a custom configuration file called nginx.conf. This configuration file will live in the root of our ClojureScript app in a folder structure like tools/nginx/nginx.conf inside the root of our demo-clojurescript-nginx ClojureScript app. So go ahead and create the folder structure:

mkdir -p tools/nginx && touch tools/nginx/nginx.conf

and then you can open nginx.conf and make it look like this:

events {}

http {

  include mime.types;

  gzip on;
  server_tokens off;

  server {
    listen 4001;
    root /var/www/app;
  }
}

Now we want give this nginx.conf file to our Nginx container so it knows how and where to serve our project from. To do this, run the following command:

docker cp tools/nginx/nginx.conf demo-clojurescript-nginx:etc/nginx/nginx.conf

at this point we want to stop our docker container so the configuration file takes effect

docker stop demo-clojurescript-nginx

and then we can start the container again.

docker start demo-clojurescript-nginx

Now we should be able to visit our site at http://localhost:4001 and see the following:

Automate Process

Everything we just did is very manual and we can save time and reduce chances of human error by automating the above process. The following will show you how to do this.

Automate Prod Artifact Builds

Go into the tools/nginx directory and create a file called Dockerfile.build and make it look like this:

# base image
FROM clojure:openjdk-11-tools-deps-slim-buster

# create dir for our app to live in
WORKDIR /app

# copy the app from our local filesystem to the docker container app dir
COPY . /app

# build our prod clojurescript artifact
RUN clojure -M:prod

# The end.  No need for a CMD to be specified because this is a build
# docker containers

A few things to note:

we use clojure instead of clj
when you run this container you want to run it from the root of the app
this will copy everything in the root project to a generically name folder called app

This docker file is responsible for building our artifacts that we performed in step 2 earlier. Now lets go ahead and move to the root of our project and run that dockerfile and see if everything works:

docker build -t \
             demo-clojurescript-nginx/build:0.0.0 \
             -f "tools/nginx/Dockerfile.build" .

The above is going to build our image and the production clojurescript object. The next step is to run a container based off the above image so that we can get the production artifacts

docker run -d \
           --name demo-clojurescript-nginx-build \
           demo-clojurescript-nginx/build:0.0.0 \
           sleep 20000

Move Production Artifacts to Local FileSystem

At this point, we want to copy the built files from the docker container to our local machine. If this were running in a CI/CD process we would have a special spot in the CI/CD environment for these temporary files. Because this is our local system, we have to create a temporary place for these things to live. Lets call this place temp/cljs-out and we will create it in the root of our demo-clojurescript-nginx repo.

mkdir -p temp/cljs-out

from here we can grab the files from our Dockerfile.build container and move them to our temp dir like this:

docker cp demo-clojurescript-nginx-build:app/resources/public/index.html ./temp/index.html
docker cp demo-clojurescript-nginx-build:app/resources/public/style.css ./temp/style.css
docker cp demo-clojurescript-nginx-build:app/out/dev-main.js ./temp/cljs-out/dev-main.js

Automate Nginx Configuration

The next step is automate step 3 from above: nginx configuration and moving the artifacts from the above to the nginx container. To do this, we need to build our own nginx container which is going to be the docker container you would actually run. SO go ahead and create another docker container inside of tools/nginx called Dockerfile which looks like this:

# base image
FROM nginx:1.17.5

# remove the default nginx configuration
RUN rm /etc/nginx/nginx.conf

# add custom nginx configuration
COPY ./tools/nginx/nginx.conf /etc/nginx

# allow nginx conf to be executable
RUN cd /etc/nginx \
    && chmod +x /etc/nginx/nginx.conf

# create working directory
WORKDIR /var/www/app

# copy our temp artifacts
COPY ./temp /var/www/app

# start nginx container
CMD /bin/bash -c "nginx -g 'daemon off;'"

now build the image

docker build -t \
             demo-clojurescript-nginx/prod:0.0.0 \
             -f "tools/nginx/Dockerfile" .

and before we run our final image stop any instances of Nginx docker containers you may still have running on port 4001. e.g.

docker stop demo-clojurescript-nginx
docker stop demo-clojurescript-nginx-build

and now we should be able to run our Nginx container

docker run -d \
           -p 4001:4001 \
           --name demo-clojurescript-nginx-prod \
           demo-clojurescript-nginx/prod:0.0.0

Now we should be able to visit http://localhost:4001 and we should be able to see

Conclusion

And with that we have successfully deployed our ClojureScript app to our own Nginx webserver. At this point, the next step is to deploy this on a server. Unfortunatley, that is out of the scope of this post, but if you are using a service like AWS or Google Cloud Platform they should have some awesome guides for deploying Nginx on their infrastructure.

Again, my hope is to outline a piece of the process. Let me know if this helped!

Students of the Game: Reloadable Code

2024-11-11T22:08:33Z

About two years ago I built a small ClojureScript app that looks like this:

This app was meant to be a bite sized learning project to level up my ClojureScript interop skills.

Aside from being gorgeoous, it had only two things to do:

User presses the Add button and 1 new Calendar Event is created
User can see a List of Calendar Events

I started the app as I always do which includes running figwheel and Hot Module Reloading (HMR). As I'm jamming away on the code I started to notice some interesting behaviour.

When I pressed the Add button, instead of 1 new Calendar Event being added, 5 were added! I paused for a moment before hard refreshing the browser. Then I clicked the Add button again. Unlike the first time, everything worked as expected; only 1 new Calendar Event was added. I smiled to myself and marvelled at my incredible detective skills: obviously the problem was HMR.

Since I obviously identified the source of the problem I decided to resolve the issue by ignoring it. So any time I made a change which triggered an HMR reload I would hard refresh the browser like a savage.

Some time later I realized that, no, the problem was not HMR...it was my code. As it turns out, HMR isn't free. It requires the code author to design and build the code to be reloadable code.

So in the intrepid spirit of craftsmanship, I have resurected my Calendar App and refactored it to be reloadable code.

Intro to Hot Module Reloading

HMR is a program which runs alongside our app which watches for changes to our .cljs files and when it sees that one of these .cljs files has changed it tells the browser to fetch the latest changes and trigger a "reload". This means our running app is automatically updated with the new code and the app state is exactly where we left it.

We like HMR because it allows us to develop faster and with less friction. Specifically, HMR can make it so:

We don't have to manually refresh our browsers
We don't have to lose our applications state
We don't have to manually recompile our code

HMR is provided by programs like figwheel, shadow-cljs or webpack .

Having said the above, just because you use figwheel or shadow-cljs doesn't mean you can get the benefits of HMR. You also have to architect your code in a specific way. Namely, you have to control side effects. In other words, you have to write reloadale code.

"Submit" Event Listeners

If you save the calendar.cljs file 5 times and then press the Add button in the Calendar App you will see it creates 5 Calendar Events.

If we inspect the console we can see that this is because our "submit" event listener is attached 5 times to the submit event. This is why when we click the Add button, we get 5 Calendar Events added instead of the expected 1.

Why is this happening? As it turns out, if you look to the code here:

(events/listen
  (.. js/document (querySelector ".calendar-form"))
  "submit"
  handle-add-event!)

The code above is invoked in our ns meaning that it runs everytime a reload is triggered. In other words, if you trigger 5 reloads it would be as if you wrote this:

(events/listen element "submit" handle-add-event!)
(events/listen element "submit" handle-add-event!)
(events/listen element "submit" handle-add-event!)
(events/listen element "submit" handle-add-event!)
(events/listen element "submit" handle-add-event!)

Wait. Didn't we say that each reload triggers a browser refresh? Not exactly. What we mean is that the ClojureScript in your app is sent to the DOM and re-run. The effect makes it appear like the browser is refreshing. Thus, triggering a reload updates your ClojureScript and re-runs your ClojureScript, but unlike your ClojureScript, whatever you did the DOM previously prior to a reload stays done.

This is why when we write reloadable code we have to control what we do to the DOM so we don't cause unexpected behaviours like 5 Calendar Events added at a time.

So how do we control what we do to the DOM to avoid these unpredictable side effects? We write reloadable code and to do this we have to know two things:

when is our code going to reload?
when is our code going to finish reloading?

figwheel, as well as other programs, provides us with a mechanism so we can answer the above 2 questions and that mechanism looks like this:

(defn ^:before-load teardown []
  ; ...do stuff
  )


(defn ^:after-load setup []
  ; ...do stuff
  )

Before we go further, lets breakdown what the above is doing. teardown and setup are nothing more than clojure functions. The only part we have to care about from the above are the ^:before-load and ^:after-load words that come before teardown and setup.

^:before-load and ^:after-load are called metadata in Clojure(Script). What makes them metadata is the ^ that comes before the : (colon).

When figwheel sees these particular pieces of metdata infront of a function it knows that it has to run our functions before and after the CLJS reloads.

Now that we know we can write code that runs before and after load we just have to figure out what we should put in these functions to make our code reloadable code.

Going back to the "submit" event listener scenario, the problem is that everytime our code reloads, a new event listener is attached to the "submit" event. But what we want is to only have 1 event listener, the newest event listener, attached to our submit. So what we need to make our code do:

before reload: remove old "submit" event listener
after reload: add new "submit" event listener

The following is what the above looks like in our code:

; before reload: remove old "submit" event listener
(defn ^:before-load teardown []
  (events/removeAll
   (.querySelector js/document ".calendar-form")))

; after reload: add new "submit" event listener
(defn ^:after-load setup []
  (events/listen
    (.. js/document (querySelector ".calendar-form"))
    "submit"
    handle-add-event!))


(defonce initial-load (setup))

What we did:

before-load - figwheel is going to call our teardown function which deletes event listeners from submit
after-load - figwheel is going to call our setup function which adds event listeners to submit

You might have also noticed that I snuck in a little something extra: initial-load. Remember how we said that before-load happens before a reload and after-load happens after a reload? This means those are only triggered when a reload is triggered. If we left it like that, our code would not work when we first visit the app. So we add a defonce so that the code which runs on the first, and only the first time, your app loads in the browser.

With the above in place go ahead and try to trigger some reloads. If everything worked, no matter how many time you trigger a reload only 1 Calendar Event should ever be created.

If you are lost at this point for any reason take comfort in the fact that writing reloadable code is not always straighforward and does require you to think deeply about what your code is doing. This is a skill that can take some time to learn.

"Change" Event Listeners

Here is the second opportunity for making our code reloadable code. Similar to the "submit" example above, we are invoking another event listener in our file for the change event:

(events/listen
  (.. js/document (querySelector "#event_start"))
  "change"
  update-event-end-dropdown!)

If you read the code, or even ran the code, you will see that this code is not a problem. Yes, if we reload our app 5 times it would do this:

(events/listen element "change" update-event-end-dropdown!)
(events/listen element "change" update-event-end-dropdown!)
(events/listen element "change" update-event-end-dropdown!)
(events/listen element "change" update-event-end-dropdown!)
(events/listen element "change" update-event-end-dropdown!)

But it's still not causing any bugs. The reason is because the code inside of update-event-end-dropdown! is destructive and not performing an additive effect like "submit". The worst that happens is that if we reload 5 times the option will get set 5 times because of (.-innerHTML start-time-dropdown).

So if this is not a bug, then why talk about it? Because even if the code is not causing problems now, it is stacking event listeners and if we change update-event-end-dropdown! to accidentally do something different, we are going to set ourselves up nicely for an interesting bug.

If neither of these arguments persuade you, that is fine and highlights the interesting part about writing reloadable code: many elements of designing your code in this way are going to be subjective and based on how you want your code to run.

Having said this, for this scenario I am going to play it safe and show you how we could fix the code:

(defn ^:after-load setup []
  (events/listen
    (.. js/document (querySelector ".calendar-form"))
    "submit"
    handle-add-event!)

  (events/listen
    (.. js/document (querySelector "#event_start"))
    "change"
    update-event-end-dropdown!))

You can see the above change here. In the next section we are going to explore more subjective goodness.

Reading [along with the code] in Calendar App, we have another invocation when the ns loads.

(set! (.. start-time-dropdown -innerHTML) (time-option-list (time-range)))

(set! (.. end-time-dropdown -innerHTML) (time-option-list (time-range 9.25)))

All these do is populate the time options in our forms time dropdowns. So the question is, if we run this multiple times in a row what happens? Similar to the "change" event listeners, the above is performing a destructive action. each time they are run they will delete the content of the select boxes and replace them with the same options. Also, unlike event listeners these do not stack. Will there be a bug? What are the problems with this?

Each time we run this code, it clears out our dropdowns and re-adds options. What if we put this in initial-load? It would only run once meaning that if we made changes to time-option-list we would not see the effect take place. But what if we know we are 100% done with time-option-list? Perhaps we don't believe their will be more changes? Maybe this justifies only putting it into the initial-load.

However, if you are in the camp that believe we should re-run this action just to be safe, then we can put it into the initial-load and after-load. But if we do this there is something that could happen. Imagine this is what I did:

select a start and end time
realize I need to make a change to the code
change the code + trigger a reload

If we move the time-option-list inside the after-load everytime a reload is triggered we are going to lose our start and end time we selected. We are losing app state. If this is concerning to you, then it is not enough to add our time-option-list to the after-load we also have to add additional code to our app to potentially save the state of the application so we don't lose it. I won't walk through what that looks like, as I wanted to bring it up as a lead to what makes HMR feel like magic: app state.

Managing App State

App State is a memory of what you did in the app. When we trigger a reload we can make it so our add does not reset its app state. For example, let's pretend I am working on my add, I add a few Calendar Events and trigger a reload. Those Calendar Events I just added will be lost. We go back to 0. This does not have to be the case though. We could tell our add to not reset the state.

To make this happen all you have to do, based on how I wrote Calendar App, is this:

; update this line
(def app-state (atom []))

; to look like this
(defonce app-state (atom []))

That's it. Now, whenever your app reloads, your state is never forgotten. The way this works is explained nicely in Hot Reload in ClojureScript. The short answer: defonce means that app-state will not reset to (atom []) when the app reloads.

This is a simple example, but it should provide some ideas for what needs to be done to make our reloadable code capable of managing state.

Conclusion

Writing reloadable code can seem tricky at first, but hopefully we can see that with ClojureScript it is an achievable and worthwhile goal. For me the benefits of writing your code like this and even thinking about these things is the understanding you gain about how your code works.

The other gain is the power that ClojureScript gives you out of the box. It takes very little to setup HMR and start writing reloadable code with the tools provided by Clojure(Script) core library. You don't need additional dependencies.

Hopefully this provides a decent example set with which to start your reloadable code journey.

Footnotes

In my head I was a heroic. Crushing out code. Delivering... I was a Titan in that moment. The truth is this is savagery at its finest.
Back
Two points here: First, HMR is not specific to ClojureScript. It can be done in JavaScript, C++ etc. I am only referencing ClojureScript because that is the focus of this article. These techiques can be shared 1:1 with JavaScript, but I have not tried yet. Second, When I said that app state is exactly where we left it, this is only true when you setup your reloadable code to work this way. I write about this in the Managing App State section of this post.
Back
You do not use all of these tools, you only need to choose one.
Back
If you like to debug using console.log statements you are going to run into a bug while debugging like this. If you run the app, add a console.log to handle-add-event! and save you will trigger a reload. Then, if you click the add button you will notice that even though you have 2 event listeners attached, only 1 console.log will fire. This is because the first event listener has the old handle-add-event! function without the console.log. So it will seem like your only 1 event listeners is firing. You can verify this again by saving the file, without making changes, and now you should see 2 logs fire.
Back

ClojureScript Test Setup

2024-11-11T22:08:33Z

This post will walk through how to setup a Test Toolchain from scratch for a ClojureScript app.

Create a Project

Start by creating a basic ClojureScript app. The easiest way to do this is by following my templates projects Quickstart guide.

Assuming you're using the templates tool from above, you would run the command in the quickstart guide and you should have a project called my-app-name which has the following folder structure:

my-app-name
├── README.md
├── deps.edn
├── dev.cljs.edn
├── prod.cljs.edn
├── resources
│   └── public
│       ├── index.html
│       └── style.css
├── src
│   └── myusername
│       └── my_app_name.cljs
└── test
    └── myusername
        └── my_app_name.cljs

Now, move into the project you just created

cd my-app-name

Install the project's JS dependencies

yarn install

Now let's make sure everything is working as expected by running the following command:

clj -M:dev

If everything worked, a new browser window should automatically open to http://localhost:9500/ and you should see the following:

I now want to draw your attention to the names of the file and folders:

├── src
│   └── myusername
│       └── my_app_name.cljs
└── test
    └── myusername
        └── my_app_name_test.cljs # <--- notice the `_test`

It's a convention in Clojure to have your tests mirror your src directory structure. Additionally, when you name the actual files containing your tests they get suffixed with _test.

Write a Test

Now that we have a project to work in, let's write some code and test it!

Open my_app_name.cljs. You will notice that some code already exists in this file. Delete all the code in the file. Type the following into the file:

(ns myusername.my-app-name)

(defn add
  [a b]
  (+ a b))

The above is just a simple function which we've written so we have something to test with. The next step is to write our first test.

Open my_app_name_test.cljs. Delete all the code in the file. Type the following into the file.

(ns myusername.my-app-name-test
  (:require
    [cljs.test              :refer-macros [deftest is]]
    [myusername.my-app-name :as my-app-name]))

(deftest test-add-function
  (is (= (my-app-name/add 1 1) 2)))

Let's review the test we just wrote. cljs.test is a small library with everything you need to test ClojureScript code. Among other things, it comes with:

Test Decleration Utils e.g. deftest
- deftest let's us define a test. In our example, we defined a test called test-add-function.
Test Assertion Library e.g. is
- is is a convenience wrapper around a try-catch block
Test Runner
- we haven't introduced this to you yet, but it's called run-tests

Now that we have written a test, the next section will show you how to run the test.

Run tests with cljs-main

To run our tests, we need to create a namespace that will import all of our tests and then run them. We can refer to this namespace as our test_runner, but you can also think of it as the test entrypoint.

Start by creating a new file in test/myusername. Call this file test_runner.cljs. Open test_runner.cljs and type the following into it:

(ns myusername.test-runner
  (:require
    [cljs.test :refer-macros [run-tests]]
    [myusername.my-app-name-test]))

(run-tests 'myusername.my-app-name-test)

What the above does is:

Import our test namespaces e.g. myusername.my-app-name-test
Run all of our rests by calling run-tests

Now that we have a file which knows how to run our tests, we need a command in our app which we call to run the tests.

Open the deps.edn file. Type the following new alias into the file:

{
;; ...

:test {:main-opts ["--main"    "cljs.main"
                   "--compile" "myusername.test_runner"
                   "--repl"]}}

From here, we just have to run the tests. To do this, go to your terminal and run the test alias:

clj -M:test

What the above alias is going to do is:

compile your cljs to js
automatically open your app in your default browser
render the default ClojureScript index.html
run the tests in the browser

But you will notice that you won't see the tests anywhere. So, what happened? Your test report or output won't be found in the browser, rather, you will find it in your terminal and will look something like this:

➜ clj -M:test
ClojureScript 1.11.60
cljs.user=>
Testing myusername.my-app-name-test

Ran 1 tests containing 1 assertions.
0 failures, 0 errors.

Note that you could also have the test report displayed in your browser console by adding (enable-console-print!) in your test-runner namespace before you invoke run-tests:

(ns myusername.test-runner
  (:require
    [cljs.test :refer-macros [run-tests]]
    [myusername.my-app-name-test]))

(enable-console-print!) ; new

(run-tests 'myusername.my-app-name-test)

Cancel out of the clj -M:test process in your terminal. Run clj -M:test again. Check the browser console and you should see the tests logged there as well.

Note that it's pretty cumbersome to have to stop and re-run tests all the time. Instead, we can tell ClojureScript to watch the src and test directory so that every time you update files in your src or test dir they will automatically be recompiled on save. To make this happen, update your :test alias to look like this:

{:test {:main-opts ["-m"  "cljs.main"
                    "-w"  "src:test" ; new
                    "-c"  "myusername.test_runner"
                    "-r"]}}

And that's everything involved in setting up a ClojureScript only Test Toolchain. For those who want to take it a step further, let's see how we can configure figwheel to run these tests.

Run tests with figwheel

Because we are using the templates reagent template, we have everything we need to run our tests using figwheel. In fact, most everything we needed from the previous section will be used in this section with a few changes. As you will see, one awesome feature of using figwheel for testing is you get more tooling, with less configuration.

To recap, we already have:

A test
A test runner

The only thing we have to change is a small piece of our test runner. Open up test_runner.cljs and update the following

(ns myusername.test-runner
  (:require
    [cljs-test-display.core] ; new
    [figwheel.main.testing :refer-macros [run-tests]] ; new
    [myusername.my-app-name-test]))

(run-tests (cljs-test-display.core/init! "app-testing")) ; updated

The next step is to open your dev.cljs.edn file and add a :extra-main-files key set like this:

^{:auto-bundle      :webpack
  :watch-dirs       ["src" "test"] ; updated
  :css-dirs         ["resources"]
  :extra-main-files {:testing {:main myusername.test-runner}}}; new
{:main myusername.my-app-name}

What the above does is build and run your tests, like we did with the :test alias in the previous section.

The difference is that we are going to do this as part of our :dev alias. This is great because it means we have a single file watcher and HMR process runing in the same process as our development build. So now, we can develop our app and tests at the same time in one simple command.

To run the above:

clj -M:dev

Now you can visit your app at http://localhost:9500 and your tests at http://localhost:9500/figwheel-extra-main/testing

When you visit localhost:9500/figwheel-extra-main/testing you should see something like this:

The above is a graphical version of the textual test report that we got when we ran the tests using cljs.test. From here, you can modify your code and your figwheel-extra-main/testing will not only rebuild, but live update creating a nice developer experience.

Runtime Environments

Up until now, we haven't discussed Runtime Environments. Runtime Environments are important because they impact your test results.

When we ask which runtime environment our JS code is running in we want to know if it's running in a browser or server environment. Then, we also need to know which browser (Safari, Chrome, Firefox) or server environment (Node, Dino, Bun) our code is specifically running in.

Right now, if you run your code like we did in the run tests with cljs.main section, your code will be run in a Browser Environment. If you were to set --repl-env to node then your code would be run in a Node Environment.

Making sure we're testing against the right environments is important because the behavior and APIs made available to you will change based on the environment your code's run in.

For example, you won't have the window object in Node, so it wouldn't be a good idea to test your browser code in a Node server environment.

Another consideration is test performance. As it turns out, it's not always desirable or possible to test your browser code directly in the browser. For example, you may run into a scenario where you want to run your code in your CI/CD process. When this is the case, you will want to setup a Headless Browser Runtime Environment. The following section will show you how to do this.

Headless Browser Runtime Environment

This section is going to illustrate how to run your ClojureScript tests using headless chrome.

This is something we want to configure so we can run our tests as part of our CI/CD process.

The reason we do this is because in CI/CD we don't need a browser GUI. The GUI is slow and uses more computer resources. For this reason, we configure our tests to run in a headless environment. Here are some example of headless JS environments

For our purposes I use headless chrome which is Chrome without the GUI.

The following sub-sections will walk through the steps required to setup this environment and teach figwheel to execute your tests inside of it.

Step 1 Setup A Headless Test Runner

Open test_runner.cljs. Make it match the following:

(ns myusername.test-runner
  (:require
    [figwheel.main.testing :refer-macros [run-tests-async]]
    ; tests here
    [myusername.my-app-name-test]))

(defn -main [& args]
  (run-tests-async 10000))

Step 2 Add a test config

Create a new file in the root of my-app-name called test.headless.cljs.edn. Open test.headless.cljs.edn and type the following into it:

^{:auto-bundle         :webpack
  :ring-server-options {:port 9504}}
{:main            myusername.test-runner
 :infer-externs   true
 :output-dir      "target/public/cljs-out"
 :output-to       "target/public/cljs-out/main.js"

Step 3 Configure Figwheel

Open deps.edn and add a :test-headless alias:

{:paths
 ["src" "test" "resources" "target"]

 :deps
 {org.clojure/clojurescript  {:mvn/version "1.11.60"}

  com.bhauman/figwheel-main  {:mvn/version "0.2.18"}

  reagent                    {:mvn/version "1.2.0"}}

 :aliases
 {:dev
  {:main-opts ["-m"  "figwheel.main" "--build" "dev" "--repl"]}

  :test-headless ; new alias
  {:main-opts ["--main"         "figwheel.main"
               "--compile-opts" "test.headless.cljs.edn"
               "--fw-opts"      "{:launch-js [\"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome\" \"--headless\" \"--remote-debugging-port=9222\" :open-url]}"
               "--main"         "myusername.test-runner"]}}}

That's it. We are ready to run our headless browser testing setup. Try it out by running clj -M:test-headless in your terminal.

If it all worked you should see something like this:

# ...

Testing myusername.my-app-name-test

Ran 1 tests containing 1 assertions.
0 failures, 0 errors.
:figwheel.main.testing/success

You're going to notice that you have to re-run this every time you want to run your headless tests. This is to be expected. The thing with this approach is that we have only really configured it to be run by our CI environment and also as a quick sanity check for newcomers to our project. Could we make it do more? Yup! You can take this and connect it to figwheel's file watching mechanism and have it behave exactly like the browser testing setup.

Alternative Tools

Up until now, i've shown you only cljs.test. The reason is because it's simple, does what we need and means we don't have to pull in more deps.

Having said this, you might want more features. That's totally understandable and possible with this setup. Part of the reason I broke down cljs.test into smaller groups of functionality like assertion library, test definitions, test reporting and test runner is because it helps you see that you're not looking to replace everything, but maybe just a small piece of something.

Now that we know what some of these pieces are you should be in a position to replace them if you need to. With this in mind, here are some alternatives you can consider if you want to experiment with different tools.

To replace your assertion libraries and test definitions these are some popular libraries in Clojure(Script)

For now I recommend sticking with cljs.test and then look into one of the above when/if the need arises.

And replacements for test-runners and test reporters

Next Steps

The goal here was to layout some context. Point you to tools and explore how and what to configure in your tooling for testing ClojureScript. From here, play with the setup, see how far it takes you and run with it. Here are some other resources you might be interested in:

Finally, there is no "right" or "wrong" testing tool. Start. Figure out what works and what doesn't work and then iterate.

What the Reagent Component?!

2024-11-11T22:08:33Z

Did you know that when you write a form-1, form-2 or form-3 Reagent component they all default to becoming React class components?

For example, if you were to write this form-1 Reagent component:

(defn welcome []
  [:h1 "Hello, friend"])

By the time Reagent passes it to React it would be the equivalent of you writing this:

class Welcome extends React.Component {
  render() {
    return <h1>Hello, friend</h1>
  }
}

Okay, so, Reagent components become React Class Components. Why do we care? This depth of understanding is valuable because it means we can better understand:

JavaScript, ES6 classes and the idea behind "syntax sugar"
React's strategy for distinguishing class and function components
How ClojureScript interacts with JavaScript

The result of all of this "fundamental" learning is we can more effectively harness JavaScript from within ClojureScript.

A Pseudoclassical Pattern

The reason all of your Reagent components become class components is because all of the code you pass to Reagent is run through an internal Reagent function called create-class.

create-class is interesting because of how it uses JavaScript to transform a Reagent component into something that is recognized as a React class component. Before we look into what create-class is doing, it's helpful to review how "classes" work in JavaScript.

Prior to ES6, JavaScript did not have classes. and this made some JS developers sad because classes are a common pattern used to structure code and provide support for:

instantiation
inheritance
polymorphism

But as I said, prior to ES6, JavaScript didn't have a formal syntax for "classes". To compensate for the lack of classes, the JavaScript community got creative and developed a series of instantiation patterns to help simulate classes.

Of all of these patterns, the pseudoclassical instantiation pattern became one of the most popular ways to simulate a class in JavaScript. This is evidenced by the fact that many of the "first generation" JavaScript libraries and frameworks, like google closure library and backbone, are written in this style.

The reason we are going over this history is because the thing about a programming language is there are "patterns" and "syntax". The challenge with "patterns" is:

They're disseminated culturally (tribal knowledge)
They're difficult to identify
They're often difficult to search
They often require a deeper knowledge to understand how and why to use a pattern.

The last point in praticular is relevant to our conversation because patterns live in a context and assume prior knowledge. Knowledge like how well we know the context of a problem, the alternative approaches to addressing a problem, advancements in a language and so on.

The end result is that a pattern can just become a thing we do. We can forget or never know why it started in the first place or what the world could look like if we chose a different path.

For example, the most common way of writing a React class component is to use ES6 class syntax. But did you know that ES6 class syntax is little more than syntactic sugar around the pseudoclassical instantiation pattern?

For example, you can write a valid React class component using the pseudoclassical instantiation pattern like this:

// 1. define a function (component) called `Welcome`
function Welcome(props, context, updater) {
  React.Component.call(this, props, context, updater)

  return this
}

// 2. connect `Welcome` to the `React.Component` prototype
Welcome.prototype = Object.create(React.Component.prototype)

// 3. re-define the `constructor`
Object.defineProperty(Welcome.prototype, 'constructor', {
  enumerable: false,
  writable: true,
  configurable: true,
  value: Welcome,
})

// 4. define your React components `render` method
Welcome.prototype.render = function render() {
  return <h2>Hello, Reagent</h2>
}

While the above is a valid React Class Component, it's also verbose and error prone. For these reasons JavaScript introduced ES6 classes to the language:

class Welcome extends React.Component {
  render() {
    return <h1>Hello, Reagent</h1>
  }
}

For those looking for further evidence, we can support our claim that ES6 Classes result in same thing as what the pseudoclassical instantiation pattern produces by using JavaScript's built-in introspection tools to compare the pseudoclassical instantiation pattern to the ES6 class syntax.

pseudoclassical instantiation pattern:

function Welcome(props, context, updater) {
  React.Component.call(this, props, context, updater)

  return this
}

// ...repeat steps 2 - 4 from above before completing the rest

var welcome = new Welcome()

Welcome.prototype instanceof React.Component
// => true

Object.getPrototypeOf(Welcome.prototype) === React.Component.prototype
// => true

welcome instanceof React.Component
// => true

welcome instanceof Welcome
// => true

Object.getPrototypeOf(welcome) === Welcome.prototype
// => true

React.Component.prototype.isPrototypeOf(welcome)
// => true

Welcome.prototype.isPrototypeOf(welcome)
// => true

ES6 class

class Welcome extends React.Component {
  render() {
    console.log('ES6 Inheritance')
  }
}

var welcome = new Welcome()

Welcome.prototype instanceof React.Component
// => true

Object.getPrototypeOf(Welcome.prototype) === React.Component.prototype
// => true

welcome instanceof React.Component
// => true

welcome instanceof Welcome
// => true

Object.getPrototypeOf(welcome) === Welcome.prototype
// => true

React.Component.prototype.isPrototypeOf(welcome)
// => true

Welcome.prototype.isPrototypeOf(welcome)
// => true

What does all of this mean? As far as JavaScript and React are concerned, both definions of the Welcome component are valid React Class Components.

With this in mind, lets look at Reagent's create-class function and see what it does.

What Reagent Does

The history lesson from the above section is important because create-class uses a modified version of the pseudoclassical instantiation pattern. Let's take a look at what we mean.

The following code sample is a simplified version of Reagent's create-class function:

function cmp(props, context, updater) {
  React.Component.call(this, props, context, updater)

  return this
}

goog.extend(cmp.prototype, React.Component.prototype, classMethods)

goog.extend(cmp, React.Component, staticMethods)

cmp.prototype.constructor = cmp

What we have above is Reagents take on the pseudoclassical instantiation pattern with a few minor tweaks:

// 1. we copy to properties + methods of React.Component
goog.extend(cmp.prototype, React.Component.prototype, classMethods)

goog.extend(cmp, React.Component, staticMethods)

// 2. the constructor is not as "thorough"
cmp.prototype.constructor = cmp

Exploring point 1 we see that Reagent has opted to copy the properties and methods of React.Component directly to the Reagent compnents we write. That is what's happening here:

goog.extend(cmp.prototype, React.Component.prototype, classMethods)

If we were using the the traditional pseudoclassical approach we would instead do this:

cmp.prototype = Object.create(React.Component.prototype)

Thus, the difference is that Reagent's approach copies all the methods and properties from React.Component to the cmp prototype where as the second approach is going to link the cmp prototype to React.component prototype. The benefit of linking is that each time you instantiate a Welcome component, the Welcome component does not need to re-create all of the React.components methods and properties.

Exploring the second point, Reagent is doing this:

cmp.prototype.constructor = cmp

whereas with the traditional pseudoclassical approach we would instead do this:

Object.defineProperty(Welcome.prototype, 'constructor', {
  enumerable: false,
  writable: true,
  configurable: true,
  value: Welcome,
})

The difference in the above approaches is that if we just use = as we are doing in the Reagent version we create an enumerable constructor. This can have an implication depending on who consumes our classes, but in our case we know that only React is going to be consuming our class components, so we can do this with relative confidence.

What is one of the more interesting results of the above two Reagent modifications? First, if React depended on JavaScript introspection to tell whether or not a component is a child of React.Component we would not be happy campers:

Welcome.prototype instanceof React.Component
// => false...Welcome is not a child of React.Component

Object.getPrototypeOf(Welcome.prototype) === React.Component.prototype
// => false...React.component is not part of Welcomes prototype chain

welcome instanceof React.Component
// => false...Welcome is not an instance of React.Component

welcome instanceof Welcome
// => true...welcome is a child of Welcome

Object.getPrototypeOf(welcome) === Welcome.prototype
// => true...welcome is linked to Welcome prototype

console.log(React.Component.prototype.isPrototypeOf(welcome))
// => false...React.Component not linked to the prototype of React.Component

console.log(Welcome.prototype.isPrototypeOf(welcome))
// is Welcome is the ancestory?

What the above shows is that Welcome is not a child of React.component even though it has all the properties and methods that React.Component has. This is why were lucky that React is smart about detecting class vs. function components.

Second, by copying rather than linking prototypes we could inccur a performance cost. How much of a performance hit? In our case this cost is likely negligible.

Conclusion

In my experience, digging into the weeds and going on these detours has been an important part of my growth as a developer. The weeds have allowed me to be a better programmer because I'm honing my ability to understand challenging topics and find answers. The result is a strange feeling of calm and comfort.

This calm and comfort shouldn't be overlooked. So much of our day-to-day is left unquestioned and unanalyzed. We let knowledge become "cultural" or "tribal". This is scary. It's scary because it leads to bad decisions because no one around us knows the whys or wherefores. Ultimately, it's a bad habit. A bad habit which is seen by some as a virtue because it would simply take too much time for to learn things ourselves. That's until you actually start doing this kind of work and spend time learning and observing and seeing that these "new things" we're seeing all the time aren't really new, but just another example of that old thing back.

Start a ClojureScript App from Scratch

2024-11-11T22:08:33Z

In this post we'll walk through my approach to setting up a Clojure(Script) app from scratch. My ultimate goal is to help alleviate the nagging perectionist feelings we get when starting new projects.

If you plan on following along with this post, please be sure to have Clojure installed and working. Not sure? Want to know how? I recommend taking a look at my free Getting Started with Clojure(Script) Youtube series which will take you through the whole process or checkout the official written ClojureScript Quickstart Guide.

Setup Project Structure

This section covers the file & folder structure of our application: What goes where and why.

To start a new project we need a name. In Clojure/Script the convention is to combine your "company" and "project" name. For example, if we worked for Nike and we're building an app called Fit Queens then our app structure would look like src/nike/fit_queens.cljs.

For the demo code in this post, we'll pretend our company name is tallex and the app is called time dive.

With this in mind, let's get to step 1: create your projects files and folders!

Step 1 - Add the Files and Folders

Start by creating each file and folder exactly as seen below:

.
├── README.md
├── resources
│   ├── index.html
│   └── style.css
├── src
│   └── tallex
│       └── time_dive.cljs
└── tests
    └── tallex
        └── time_dive_tests.cljs

Step 2 - Add HTML

Add some HTML so when the page renders we see something. All web apps start with an HTML file. Think of HTML as the "bones" of your web app.

Open your index.html file and add the following:

<!DOCTYPE html>
<html>
  <head>
    <title>Time Dive</title>
    <link rel="stylesheet" type="text/css" href="style.css" />
  </head>
  <body>
    <h1 class="site__title">
      <span class="site__title-text">Time Dive</span>
    </h1>
    <script src="/out/main.js"></script>
  </body>
</html>

Step 3 - Add CSS

Now we can write some CSS. Open the style.css file and add these styles:

:root {
  --color-purple: rgba(197, 18, 193, 1);
  --color-pink: rgba(241, 50, 50, 1);
}

body {
  margin: 0;
  height: 100vh;
  display: flex;
  font-family: Arial;
  align-items: center;
  justify-content: center;
}

.site__title {
  font-size: 100px;
  width: 50%;
  text-align: center;
}

.site__title-text {
  background: -webkit-linear-gradient(
    34deg,
    var(--color-purple),
    var(--color-pink)
  );
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}

Step 4 - Add ClojureScript

Now let's write some ClojureScript. Open time_dive.cljs and type the following code:

(ns tallex.time-dive)

(js/console.log "Hello, Time Dive!")

The above tells Clojure/Script you're creating a namespace called tallex.time-dive. This namespace is going to be the entry point of our app.

There are a few implicit details which I want to highlight when it comes to namespaces. Firstly, namespaces follow the folder path. Secondly, if a folder or file in your namespace has multiple words in it, like time_dive, when we're write our Clojure/Script namespace you must use dashes and not underscores to separate them. For example, you have a file labelled time_dive and when we write it in Clojure/Script we would write time-dive. Lastly, best practice is to multi-segment our namespace name. A multi-segmented name is when we have multipe words/phrases separated by dots. For example, tallex.time-dive is multi-segmented. The first segment is tallex and the second is time-dive. Best practice is to have two or more segments. If we only have one segment it can lead to name conflicts. Having said this, it's not the end of the world if you only have a single-segment namespace.

Step 5 - Add ClojureScript Tests

Good tests are the Alfred to a software engineers Batman. Open up that time_dive_tests.cljs file and add the following:

(ns tallex.time-dive-tests)

(js/console.log "Hello, Time Dive Tests!")

This concludes setting up the project structure and boilerplate code. The next thing to do is setup some tooling to run our Clojure(Script) app.

Running and Developing ClojureScript

To run our Clojure/Script project we'll use clj tool: which will allow us to:

run clojure programs
resolve transitive dependencies
build classpaths

Why do we need this? Because while we're developing our app we want to be able to use tools like ClojureScript, Figwheel etc to make our development experience pleasant. To do this, we start by adding these tools (deps) to our project.

Step 6 - Add deps file

Start by creating a deps.edn file in the root of our project and then make it look like this:

{:paths
 ["src" "tests" "resources"]

 :deps
 {org.clojure/clojurescript {:mvn/version "1.11.60" }}

 :aliases
 {:dev {:main-opts ["-m"  "cljs.main"
                    "-ro" "{:static-dir,[\".\",\"out\",\"resources\"]}"
                    "-w"  "src"
                    "-c"  "tallex.time-dive"
                    "-r"]}}}

Before we continue, let's review what our deps.edn file is doing:

:paths tells clj where to look for clojure code. Also known as a classpath
:deps tells clj which dependencies our app needs. Right now our only dependency is ClojureScript.
:aliases are like shortcuts. We can store long commands, or alternate dependencies in these.

Right now, we only have one alias called dev, but we will eventually have others like prod and test. The aliases allow us to run our app in different ways. Right now, our dev alias says: run ClojureScript. Specifically:

"-m" run cljs.main (run clojurescript).
"-ro" teach the CLJS repl where to find static files e.g. html, css etc.
"-w" watch all files in src dir and recompile when they are changed.
"-c" compile our app entry point: tallex.time-dive.
"-r" run a REPL and connect it to the browser.

Now that we have a rough idea of what is going on we're ready to take our app for a test drive.

Open a terminal, move into the root of the app and run the following command:

clj -M:dev

wait a bit for the above to run. If it worked, you should see that a browser tab/window automatically opens and you'll see the HTML and CSS we coded above:

Before we jump over to the next section I want to draw your attention to the fact that we have zero dependencies. Think about this: our files are being watched, code is recompiled on save, we are greeted with a browser repl and all of this with zero dependencies. Yes, we are still missing a few niceties, but we are not done yet.

Setup a ClojureScript Toolchain

As I noted, we have zero dependencies and already have a powerful toolchain. However, the developer experience can be better. This section will take our toolchain to the next level by introducing figwheel.

figwheel is a popular ClojureScript tool and a must have for my workflow. Figwheel has many features, but we are only going to focus on the main ones. These include:

live ClojureScript and CSS Reloading
Informative error messages
Build configurations for prod, dev, test et al.

Now that we know what figwheel does, let's see how to make it do the things.

Step 7 - Add Figwheel

It starts by adding figwheel as a dependency. We do this by opening the deps.edn file and add the line you see highlighted below:

; highlight-range{7}
{:paths
 ["src" "tests" "resources"]

 :deps
 {org.clojure/clojurescript {:mvn/version "1.11.60"}

  com.bhauman/figwheel-main {:mvn/version "0.2.18"}}

 ; ...
 }

Step 8 - Add build configuration

A build configuration is we configure both figwheel and the ClojureScript compiler . In this section, we'll show you what a development build configuration looks like.

Create a new file in the root of our ClojureScript app called dev.cljs.edn and add the following code to it:

^{:watch-dirs ["src"]
  :css-dirs   ["resources"]}
{:main tallex.time-dive}

What does all of the above mean?

:watch-dirs - when any cljs files change in src directory figwheel recompiles and re-loads the browser.
:css-dirs - when css files change in the resources directory figwheel recompiles and re-loads them in the browser
:main - This is an option that figwheel passes to the ClojureScript compiler which tells the compiler which file is our apps entry point.

If the above sounds like it overlaps with how we configured our project in Step 6, you're right. Now that we're using Fighwheel we don't need the -w, -r and -c flags we originally added to our dev alias. We'll update this in the next step.

Step 9 - Update :dev Alias

We need to update our dev alias to call figwheel instead of calling ClojureScript.

Open deps.edn and make it look like this:

{:paths
 ["src" "tests" "resources"]

 :deps
 {org.clojure/clojurescript {:mvn/version "1.11.60"}

  com.bhauman/figwheel-main {:mvn/version "0.2.18"}}

 :aliases
 {:dev {:main-opts ["-m"  "figwheel.main" "--build" "dev" "--repl"]}}}

Time for sanity check to make sure everything is still working. Run the following command:

clj -M:dev

Your app should run, but you will notice that you get the following screen:

This appears because figwheel is looking for our index.html in resources/public. Up until now we put our index.html file directly under the resources dir. So, our next step is to move our index.html file.

Step 10 - Restructure resources dir

Go ahead and add a public directory to the resources dir and move your index.html and style.css into it.

Your folder structure should look like this:

.
├── README.md
├── deps.edn
├── dev.cljs.edn
├── resources
│   └── public
│       ├── index.html
│       └── style.css
├── src
│   └── tallex
│       └── time_dive.cljs
└── tests
    └── tallex
        └── time_dive_tests.cljs

We also need to update the script tag in our index.html file.

<script src="/cljs-out/dev-main.js"></script>

The reason we update the script tag because figwheel is going to build your ClojureScript in a different folder than clj did.

time to run the app again:

clj -M:dev

The toolchain is now in place, but we are still missing the great and powerful Hot Module Reloading.

Hot Module Reloading

Hot Module Reloading (HMR) is the "killer feature" of React development. So much so that HMR and React are often spoken in the same breath as if the two are linked in some way. The two are separate things entirely though. Truth is, as long as you write reloadable code, you can achieve HMR.

This is the catch though: writing reloadable code can be tricky and time consuming. Writing reloadable code is made much easier when you write your code using React. This is likely part of the reason the two are seen as linked.

figwheel offers a framework / library agnostic mechanism to support your ability to write HMR. Specifically, figwheel gives us hooks which we specify in the namespace where we want to take advantage of HMR.

The way it works is when we write HMR we have to tell our app how to tear itself down and setup again when files are re-compiled. We have to write these functions ourselves. What figwheel helps with is providing hooks like :after-load and :before-load which will call our setup and teardown functions.

Step 11 - Refactor for Figwheel

This section will illustrate how to use figwheel hooks.

Open time_dive.cljs. Currently, our time-dive namespace is logging "Hello, Time Dive" on each reload. We could however only have it log on re-compile by adding a hook like this:

(ns ^:figwheel-hooks tallex.time-dive)

(defn ^:after-load re-render []
  (js/console.log "Hello, Time Dive!"))

Now when you try to run the app you will notice that the console.log will only log when there has been a reload. not log the first time but only after each save. Things to take note of:

^:figwheel-hooks - meta data telling figwheel we want to use hooks in our namespace
^:after-load - meta data telling figwheel that we want it to run the function, re-render, after each compile

reloadable code is a rich topic and my hope is to show you how it works with CLJS and figwheel and that it's a way you write your code just as much as a helper tool.

Add Reagent

You could use a bunch of JS frameworks in ClojureScript, but the ClojureScript community loves React and the community has made wrappers to make React easier to use in ClojureScript.

While there are many wrappers the most popular React wrapper is currently Reagent so we will show you how to use that.

Step 12 - Refactor for Reagent

In addition to adding Reagent we are going to update our deps.edn, html, css and cljs.

Open the deps.edn file and making it look like this:

; highlight-range{9}
{:paths
 ["src" "tests" "resources"]

 :deps
 {org.clojure/clojurescript {:mvn/version "1.11.60"}

  com.bhauman/figwheel-main  {:mvn/version "0.2.18"}

  reagent                   {:mvn/version "1.2.0"}}


 :aliases
 {:dev {:main-opts ["-m"  "figwheel.main" "--build" "dev" "--repl"]}}}

Next we can open our index.html file and modify as follows:

<!-- highlight-range{8,10} -->
<!DOCTYPE html>
<html>
  <head>
    <title>Time Dive</title>
    <link rel="stylesheet" type="text/css" href="style.css" />
  </head>
  <body>
    <div id="root"></div>

    <script src="/cljs-out/dev-main.js"></script>
  </body>
</html>

Finally open our time-dive namespace and add a few things:

(ns ^:figwheel-hooks tallex.time-dive
  (:require
    [reagent.dom :as r.dom]))


(defn app []
  [:h1.site__title
    [:span.site__title-text "Time Dive"]]])


(defn mount []
  (r.dom/render [app] (js/document.getElementById "root")))


(defn ^:after-load re-render []
  (mount))


(defonce start-up (do (mount) true))

A little about the above:

app is our first example of a Reagent component
mount a function. When called, it will display our time-dive app
re-render a function with a hook. When called, it reloads our app. It supports the HMR part
defonce is used to control side effects.

Last step: open up style.css and change the body tag to #root

/* replace ... */
body {
  /* ... */
}

/* with ... */
#root {
  /* ... */
}

Ready to see if it all worked? Run clj -M:dev and marvel at your ClojureScript SPA.

Conclusion

At this point we have created a ClojureScript app from scratch and provided a solid foundation which should allow you to take this app in any direction you like. Of course, I did not go into details beyond the initial phase, but if you are interested in possible next steps or sources for inspiration, here are a few that I often recommend.

These resources are great next steps for learning to work with Clojure(Script).

Footnotes

You will notice I spell ClojureScript in two ways: ClojureScript or Clojure(Script). The difference: The first is me saying "Just ClojureScript" and the second is me saying "this applies to both Clojure and ClojureScript". The purpose is because Clojure and ClojureScript are 95% the same language, same build tools etc. I have found it helpful to make this clear early on.
Back
Technically the README, Resources and tests files/dirs are not needed, but I always include them by default because to me, taking the time to setup things well in the beginning saves us time later. Also keep in mind that you don't have to follow my structure. There is no real science here other than this is a sane structure I have evolved and come to trust through use in production. Sanity Check: your project should look like this: commit 96fafa5.
Back
You will notice HTML, CSS, Images etc will go in our Resources dir. This is not a hard and fast rule, but it is a helpful convention. Also, sanity Check: commit 58975c
Back
Sanity Check: commit 3aab28
Back
Sanity Check: commit 863278
Back
The dominant convention is to name your entry point core.cljs. This is something that comes from the build tool lein and it's a silly convention because it provides us with no semantics. It's easy to want to do this though because other languages like JavaScript do this with their index.js and python with main.py and so on. Resist the urge and try to give your entry point a meaningful name.
Back
Sanity Check: commit 90a576
Back
Other tools include lein and boot, however the Clojure Tools are currently the most popular choice for new projects. Feel free to learn more by reading What Are The Clojure Tools:
Back
Sanity Check: commit ba182b
Back
When I say "toolchain" I mean things like build the app for production and dev, HMR, live CSS reloading. All the things needed to make development life easy and get your app from your local environment to a production ready state.
Back
There is also shadow-cljs which does some great stuff and is the more popular tool. Okay, why am I teaching Figwheel then? Figwheel does less and this is important to me. It adds testing facilities, a file-watcher and some conveniences and no more. Compare this to shadow-cljs which actually adds to the CLJS language itself. For example, it supports a non-standard form of requiring files. I find that the conveniences it provides often serves to confuse users.
Back
Sanity Check: commit 7d642c
Back
Clojars is not the only way to find versions, or even gain access to libraries. Another place to look is on Github where the source code for your packages live. In addition, you can even specify a specific hash to download the packages directly from github. Feel read to read more about that CLI and Deps
Back
I believe the difference between ClojureScript and Figwheel options is a great source of confusion for new ClojureScript developers. I feel this way because it requires an understanding of where one library ends and the other begins. Just know that Figwheel is going to be running the ClojureScript Compiler for you which is why both options can all look like one thing. If you are ever not sure, visit the links.
Back
Sanity Check: commit 46e469
Back
Sanity Check: commit 4b6b65
Back
Sanity Check: commit 4c8cbd
Back
Sanity Check: commit e1cf66
Back

Deploy ClojureScript to Github Pages

2024-11-11T22:08:33Z

Here's a small example of what it looks like to deploy a static website with some ClojureScript to Github Pages. I'll start by introducing some key cocepts and then move into how we actually do the thing.

What is ClojureScript?

ClojureScript, like Elm or Reason, is a compile to js programming language. ClojureScript is different from JavaScript in a few ways.

It's a functional language
It's a lisp (AKA: Not C style syntax)
It's development and design is intentional

Some of the more pragmatic differences

The culture of the language avoids breaking changes
Write your frontend and backend in one language
Out-of-the-box tools to help you solve problems better

If nothing else, ClojureScript is guarenteed to make you think different.

Github Pages and Static Sites?

Github Pages is a service provided by Github which allows you to freely host your static website.

A static website is when you write your website in html, css and javascript. You don't need to setup servers, databases or additonal server side code. The benefits:

Performance
A quick development workflow
Easier website security
Less expensive to build and host

The downsides are that static websites will not be able to acheive all the cool features of a beefy web app. Often times I will use a static website to prove a concept for an app, host docs or build marketing websites. They are cheap, fast to build and let you prove out concepts.

With this in mind, let's start coding.

Let's start by getting Clojure setup on your local machine. To do this, visit the ClojureScript Quickstart and follow the instructions there.

Not sure if you have everything setup properly? We can run a quick sanity check in your terminal by executing the following command:

clj -Stree

You should see a response like this:

org.clojure/clojure 1.11.1
  . org.clojure/spec.alpha 0.3.218
  . org.clojure/core.specs.alpha 0.2.62

Setting up your HTML

For those that went through the Github Pages quickstart, you should have a repo with a sad, empty index.html. Open your index.html and type the following:

<!DOCTYPE html>
<html>
  <head>
    <title>Github Pages + ClojureScript</title>
    <link rel="stylesheet" type="text/css" href="style.css" />
  </head>
  <body>
    <h1 class="site__title">
      <span class="site__title-text">Hello ClojureScript</span>
    </h1>
    <script src="/demo-clojurescript-gh-pages/out/main.js"></script>
  </body>
</html>

Setting up your CSS

The next thing we want to do is add a style.css file at the same level as our index.html. Type the following into it

:root {
  --color-purple: rgba(197, 18, 193, 1);
  --color-pink: rgba(241, 50, 50, 1);
}

body {
  margin: 0;
  height: 100vh;
  display: flex;
  font-family: Arial;
  align-items: center;
  justify-content: center;
}

.site__title {
  font-size: 100px;
  width: 50%;
  text-align: center;
}

.site__title-text {
  background: -webkit-linear-gradient(
    34deg,
    var(--color-purple),
    var(--color-pink)
  );
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}

Now that we have our HTML and CSS, we need to add ClojureScript.

Setting up your ClojureScript

This section will now add the absolute minimum requirements to start working with ClojureScript.

Create a file called deps.edn at the same level as our index.html file.

Open the file you've created and type the following code into it.

{:deps {org.clojure/clojurescript {:mvn/version "1.11.60" }}}

Let's recap a bit. At this point, your directory structure should look like this:

.
├── deps.edn
├── style.css
└── index.html

If yes, we are good to move onto the next step: writing ClojureScript!

Create src/demo directory. Once created, move into src/demo and create a ClojureScript file called static_website.cljs. Now our repo should look like this:


├── src
│   └──  demo
│       └── static_website.cljs
├── style.css
├── deps.edn
└── index.html

Open static_website.cljs and type the following:

(ns demo.static-website)

(js/console.log "Hello, Github Pages!")

Open your terminal and run the following command

clj -m cljs.main -d "demo-clojurescript-gh-pages/out"  -c demo.static-website -r

The above command will compile your CLJS into JS. It can take a moment to run. When completed, a browser tab will automatically open and serve your HTML, CSS and ClojureScript. If everything worked you should see a site that looks like this:

Further, if you open your browser console you should see "Hello, Github Pages!"

Build production bundle

The above is an example of how we test our code locally. After we're happy with our code, we can build it for production by running the following command:

clj -m cljs.main -O advanced -c "demo.static-website"

Once the above is done, commit your code with git, and push the code to your Github project repo and you should see your ClojureScript app live!

Conclusion

As I noted in the beginning, this is a very small example of a ClojureScript project. From here, you can go in many different directions. However, the idea is the same: turn your CLJS code into JS code and ship the JS code.

Footnotes

commit 90156b
Back
commit db9371
Back
deps.edn is a newer, more beginner friendly way of setting up a Clojure(script) project. Other popular alternatives include using tools like leiningen and boot Having said this, I recommend using deps.edn.
Back
commit 575c63
Back
The reason we are creating a demo dir nested in a src dir is because in Clojure(script) it's preferred to multi-segment our namespaces. This is both for stylistic and technical reasons.
Back
commit 347c55
Back
We are referencing demo-clojurescript-gh-pages in our index.html and as the -d or :output-dir flag for our development bundle. This is because when our code is served from Github Pages it's going to be served from https://username.github.io/project-name/ where project-name is the name of our gh pages clojurescript repo. This means that in order to serve our site in development and production, without having two script tags in our index.html we sync with what its called in production so we only have to set it once. There are other ways to achieve this, but with a goal of minimalism in mind, I feel this will do.
Back
When you run the development or production build commands they will generate a bunch of code we do not need to version control. For example, a .cpcache, demo-clojurescript-gh-pages/out, and out dirs. The only files you need to version control are the ones I have in gh pages clojurescript repo. The other ones can be ignored. If you're curious what that that looks like I have created a level 2 branch to show you.
Back