Building a React app with ClojureScript

React.js is the new hotness in the land of user interfaces. It’s descriptive approach pairs wonderfully with ClojureScript’s functional underpinnings.

This episode will show how to build an app with React, all from comfortable ClojureScript. It provides a solid foundation for diving into React wrappers like Reagent or Om later on, and it’s a welcome exercise in using ClojureScript’s interop features.

We’ll cover: elements, components, the virtual DOM, using an atom to keep application state, and attaching event handlers with component properties.

Transcript

Using React from ClojureScript

To introduce you to React, we’ll build a calculator app, this is what the result will look like.

Facebook released React onto the world three years ago, and it’s taken the world by storm. It lets you build user interfaces based on components and uni-directional data-flow.

Several ClojureScript libraries use React under the hood, notably Om and Reagent, each adding quite a bit of functionality of their own.

The React API is very small. By introducing React on its own, it will be easier to understand the unique value proposition of the various ClojureScript wrappers.

I’m basing this project on the Chestnut template. Pass in --vanilla to start without a wrapper library.

$ lein new chestnut calculator --template-version 0.14.0 -- --vanilla
Generating fresh Chestnut project.
README.md contains instructions to get you started.

Now add the dependency on React and React DOM, these are helpfully packaged by the CLJSJS project, so we can pull them in directly with Leiningen.

Also add org.clojure/core.rrb-vector and javax.xml.bind/jaxb-api, these are necessary for Figwheel to work on newer versions of Java.

(defproject calculator "0.1.0-SNAPSHOT"

  :dependencies [,,,
                 ;; add these
                 [cljsjs/react "15.1.0-0"]
                 [cljsjs/react-dom "15.1.0-0"]
                 [org.clojure/core.rrb-vector "0.0.14"]
                 [javax.xml.bind/jaxb-api "2.2.4"]
                 ]

  ,,,
  )

The Chestnut template is based on Figwheel. Figwheel takes care of instantly updating the browser whenever you make any changes, creating a great developer experience.

You can use the Figwheel plugin from the command line, it will start the automatic reloading, and also provide you with a REPL connected to the browser.

Open core.cljs and change the text of “Hello, Chestnut”. If your browser updated as soon as you saved the file, you’re good to go.

lein figwheel

(set! (.-innerHTML (js/document.getElementById "app"))
      "<h1>Hello Lambda Island!</h1>")

As usual I’m using Emacs and CIDER, so I’m starting a Figwheel REPL inside Emacs. Other editors like Cursive or Lightcode can do the same. The README that Chestnut generates has instructions to help you get set up. Or if that doesn’t work out for you just run Figwheel from a terminal.

M-x cider-jack-in-clojurescript

We need to require the two React libraries in the namespace declaration. We will access them through JavaScript globals, but we still need to require them so they get loaded.

(ns calculator.core
  (:require cljsjs.react
            cljsjs.react.dom))

To build a UI, you specify it as a tree of ReactElements, which are created by calling js/React.createElement. This function takes the type of element, in this case a "div", followed by the element’s properties, and finally followed by any child elements. Here’s a div element containing a parapgraph and an image. Make sure the properties are JS objects, not ClojureScript maps.

;; (js/React.createElement type properties
;;   children...)

(js/React.createElement "div" #js {}
  (js/React.createElement "p" #js {} "Hello from React")
  (js/React.createElement "img" #js {:src "/parrot.gif"}))

We can evaluate this to see what it looks like. There’s a chance the result will look like this:

#object[TypeError TypeError: can't convert symbol to string]

That’s not very helpful, is it? React elements contain a JavaScript Symbol, and ClojureScript doesn’t know how to display that. This problem will go away in future versions of ClojureScript. It’s taking a while because people are still debating how best to solve it across browsers (I’m looking at you Safari). We’ll give ClojureScript a helping hand, this patch isn’t perfect, but at least it gives us something to work with and works in modern browsers, just add it to the top of your code.

(extend-type js/Symbol
  IPrintWithWriter
  (-pr-writer [obj writer _]
    (write-all writer (str "#object[" (.toString obj) "]")))

And now we get a proper result! If you watched the episode on ClojureScript interop, you should recognize this as a plain JavaScript object. This is an important thing to remember: the result of createElement is a plain lightweight value object.

#js {:$$typeof Symbol(react.element)
     :type "div"
     :key nil
     :ref nil
     :props
     #js {:children
          #js [#js {:$$typeof Symbol(react.element)
                    :type "p"
                    :key nil
                    :ref nil
                    :props #js {:children "Hello from React"}
                    :_owner nil
                    :_store #js {}}
               #js {:$$typeof Symbol(react.element)
                    :type "img"
                    :key nil
                    :ref nil
                    :props #js {:src "/parrot.gif"}
                    :_owner nil
                    :_store #js {}}]}
     :_owner nil
     :_store #js {}}

Let’s remove some of the noise for a moment so we see what we’re looking at. First get rid of the #js reader tags. Also, several of these properties are merely implementation details. React needs them for internal use, but you won’t have to care about them yourself, so let’s get rid of those as well.

What’s left is pure, unadorned data. React elements are just values, React even treats them as immutable. Clojurians should be feeling right at home by now.

So React elements are plain JavaScript objects, with a type and properties, abbreviated to props. They are pure and simple data, and form a description of how your UI should look like. This description is called the Virtual DOM. We’ll see in a bit how to tell React to take this Blueprint, and build up the actual DOM.

{:type "div"
 :props  {:children [{:type "p"
                      :props {:children "Hello from React"}}
                     {:type "img"
                      :props {:src "parrot.gif"}}]}}

The first argument to createElement, the type, can be one of two things. It is either the name of an HTML element as a string, or it is a component class.

So far we’ve only seen regular HTML elements, let’s see how you would use a component.

Say you have a progress bar component, you might use it like this.

You don’t know yet how to create the component itself, but we’ll get there. Notice that you use them just as you would use regular HTML elements. They receive properties, and possibly child elements. It’s up to the component how it renders those.

(js/React.createElement ProgressBar #js {:progress 0.8})

Here’s another example, we could have a generic component that renders selectable tabs, such as the ones you find below a Lambda Island episode. This component receives two child elements, but will only render one of them at a time, depending on which tab is selected.

(js/React.createElement Tabs #js {:selectedIndex 0 :headers ["Transcript" "Show notes"]}
  (js/React.createElement Transcript #js {:text (:transcript episode)})
  (js/React.createElement ShowNotes #js {:text (:show-notes episode)}))

We’ll have a lot more to say about components, but before we do that let’s actually see React in action. We’ll take our virtual DOM, and pass it to ReactDOM.render, together with the DOM node that React should use as a container.

You can do a little dance just like the parrot is doing, because you just wrote a React app!

(ns calculator.core
  (:require cljsjs.react
            cljsjs.react.dom))

(def vdom (js/React.createElement "div" #js {}
            (js/React.createElement "p" #js {} "Hello from React")
            (js/React.createElement "img" #js {:src "/parrot.gif"})))

(js/ReactDOM.render vdom (js/document.getElementById "app"))

Before we go on let’s start making our lives a bit easier by wrapping that call to createElement. While we’re at it we can convert the properties to a JavaScript object, so we don’t have to do that for every element.

(defn element [type props & children]
  (js/React.createElement type (clj->js props) children))

(def vdom (element "div" {}
            (element "p" {} "Hello from React")
            (element "img" {:src "/parrot.gif"})))

It’s time to start building our calculator. We’ll first create a component to render the calculator’s display.

To create a React component, what you’re actually creating is a “component class”. Fill in the component class as an element’s type in the virtual DOM, and React will handle instantiating it and managing its lifecycle.

You create a Component class with a call to js/React.createClass. It takes a single JS object, known as the “specification”. This specification must at a minimum contain a render method, which returns a React element. We’ll also provide a displayName, which is useful for debugging.

(def Display
  (js/React.createClass
   #js {:displayName "Display"
        :render (fn []
                  (element "div" {:style {:border "1px solid black"
                                          :fontFamily "Monospace"
                                          :fontSize "2.5rem"
                                          :lineHeight "3rem"
                                          :textAlign "right"
                                          :width "20rem"
                                          :height "3rem"}}
                           "0"))}))

(js/ReactDOM.render (element Display {})
                    (js/document.getElementById "app"))

This might also be a good time to mention the React browser extension, available for both Firefox and Chrome. Let’s have a look. It shows us the tree that react has rendered, including components and elements.

Right now our Display always shows the same number, let’s change that. The value on display will change over time, which sounds like the kind of thing you could use an atom for. When rendering the Display, we pass it a prop to tell it what value it should currently display.

(def app-state (atom {:display 0}))

(js/ReactDOM.render (element Display {:value (:display @app-state)})
                    (js/document.getElementById "app"))

So now the Display component is going to get that value as a prop. How do we access it? In JavaScript you would use this.props.value. Interop to the rescue! We saw in the last episode how to “bind” JavaScript’s this with this-as. Here’s our first attempt, but… something’s not working.

(def Display
  (js/React.createClass
   #js {:displayName "Display"
        :render (fn []
                  (element "div" {:style {:border "1px solid black"
                                          :fontFamily "Monospace"
                                          :fontSize "2.5rem"
                                          :lineHeight "3rem"
                                          :textAlign "right"
                                          :width "20rem"
                                          :height "3rem"}}
                           (this-as t
                             (.. t -props -value))))}))

There’s a gotcha when using this-as, let’s have a look with Klipse how ClojureScript compiles it to JavaScript. Here we have two hypothetical functions x and y. In theory they do the same thing, but x binds this before calling z, while y binds it closer to where it’s being used.

If you look at the compild code for y, you can see that ClojureScript introduced an extra anonymous function, but functions in JavaScript introduce a new scope, and so this no longer refers to the same thing.

(defn x [] (this-as t (z (.. t -props))))

(defn y [] (z (this-as t (.. t -props))))

cljs.user.x = (function cljs$user$x() {
    var t = this;
    return cljs.user.z.call(null, t.props);
});

cljs.user.y = (function cljs$user$y() {
    return cljs.user.z.call(null, (function() {
        var t = this;
        return t.props;
    })());
});

Conclusion, when using this-as, always use it directly at the top level inside the function where you want to bind this. And… now it works.

(def Display
  (js/React.createClass
   #js {:displayName "Display"
        :render (fn []
                  (this-as t
                    (element "div" {:style {:border "1px solid black"
                                            :fontFamily "Monospace"
                                            :fontSize "2.5rem"
                                            :lineHeight "3rem"
                                            :textAlign "right"
                                            :width "20rem"
                                            :height "3rem"}}
                             (.. t -props -value))))}))

Now let’s try a couple values and watch it update. We see the display update on every change, because each time I save the file, Figwheel reloads and evaluates the file, including the call to ReactDOM.render. This tells React to re-render the Display wit the new properties.

(def app-state (atom {:display 1}))
;; ...
(def app-state (atom {:display 5}))
;; ...
(def app-state (atom {:display 999}))
;; ...
(def app-state (atom {:display 0}))

If I change the app-state from the REPL, then that change isn’t reflected in the browser.

cljs.user> (in-ns 'calculator.core)
nil
calculator.core> (swap! app-state update :display inc)
{:display 1}
calculator.core> (swap! app-state update :display inc)
{:display 2}
calculator.core> (swap! app-state update :display inc)
{:display 3}

That’s easy to fix though. It is possible to “watch” an atom, and have it call a function whenever it changes. First wrap ReactDOM.render in a function that takes the current application state as its argument. You need to call that function once at the top level so the UI will render when the app loads.

Finally use add-watch to call render for every state change. add-watch takes three arguments: the atom to be watched, a key to identify the watch, and the callback function.

The callback will receive the identifier key, the atom, the old state, and the new state. We only care about the new state, so you can ignore the rest.

It may seem horribly inefficient to call render time and again, but React is designed to make this efficient. It will only make the minimum amount of changes required to make the browser DOM reflect the generated virtual DOM.

(defn render [state]
  (js/ReactDOM.render (element Display {:value (:display state)})
                      (js/document.getElementById "app")))

(render @app-state)

(add-watch app-state :redraw (fn [_ _ _ state] (render state)))

Each time Figwheel loads the page, the app-state is getting redefined, so it’s always getting reset to its initial value. This can get annoying after a while, we can fix that by using defonce instead of def. If you do want to reset the app state at some point just refresh the browser.

(defonce app-state (atom {:display 0}))

Before we move on, let’s create a helper function for components the way we did with elements. As a first step we’ll just do a very basic wrapper around React.createClass

(defn component [name & {:keys [render]}]
  (js/React.createClass
   #js {:displayName name
        :render render}))

(def Display
  (component "Display"
    :render (fn []
              (this-as t
                (element "div" {:style {:border "1px solid black"
                                        :fontFamily "Monospace"
                                        :fontSize "2.5rem"
                                        :lineHeight "3rem"
                                        :textAlign "right"
                                        :width "20rem"
                                        :height "3rem"}}
                         (.. t -props -value))))))

It will be very common for components to acces their properties, how about we already look them up in the wrapper, and also convert them to a ClojureScript map so we don’t have to deal with that pesky interop in our components?

Now the render function directly receives the component’s props as a ClojureScript map. Looks much better, right? While we’re at it let’s move those styles into CSS, and use a className instead. I’ll just copy this CSS over, you can find it in the transcript so you can do the same.

(defn component [name & {:keys [render]}]
  (js/React.createClass
   #js {:displayName name
        :render (fn []
                  (this-as t
                    (render (js->clj (.-props t) :keywordize-keys true))))}))


(def Display
  (component "Display"
    :render (fn [props]
              (element "div" {:className "display"} (props :value)))))

.display {
    border: 1px solid black;
    font-family: Monospace;
    font-size: 2.5rem;
    line-height: 3rem;
    text-align: right;
    width: 20rem;
    height: 3rem;
}

.history {
    font-size: 1.5rem;
    width: 20rem;
    text-align: right;
    height: 2rem;
}

.button {
    width: 5rem;
    height: 5rem;
}

Now we’re ready to build up the rest of the calculator. I find it works well to first implement all the components and elements with placeholder values, so I have a structure to work with. Once everything is in place I start attaching functionality.

History and Display are straightforward, a single “div” with some styling.

(def History
  (component "History"
    :render (fn [props]
              (element "div" {:className "history"} "5 + 20 +"))))

(def Display
  (component "Display"
    :render (fn [props]
              (element "div" {:className "display"} (props :value)))))

To implement the Keypad we’ll first create a component for an individual button.

(def Button
  (component "Button"
    :render (fn [props]
              (element "button" {:className "button"} "-"))))

Now we can create the keypad, which consists of four rows of four buttons each. We need to wrap the rows in an extra div, because render can only return a single element.

(def Keypad
  (component "Keypad"
    :render (fn [props]
              (element "div" {}
                (element "div" {}
                  (element Button {})
                  (element Button {})
                  (element Button {})
                  (element Button {}))
                (element "div" {}
                  (element Button {})
                  (element Button {})
                  (element Button {})
                  (element Button {}))
                (element "div" {}
                  (element Button {})
                  (element Button {})
                  (element Button {})
                  (element Button {}))
                (element "div" {}
                  (element Button {})
                  (element Button {})
                  (element Button {})
                  (element Button {}))))))

And finally it all comes together in the Calculator component. Render it instead of just the display, and let’s see how that looks. The buttons and “history” component aren’t hooked up yet, but the display should still show the correct value.

(def Calculator
  (component "Calculator"
    :render (fn [props]
              (element "div" {}
                (element History {})
                (element Display {:value (props :display)})
                (element Keypad {})))))

(defn render [state]
  (js/ReactDOM.render (element Calculator state)
                      (js/document.getElementById "app")))

Let’s first fix those buttons. We’ll give each button a label property, and render its value onto the button.

(def Button
  (component "Button"
    :render (fn [props]
              (element "button" {:className "button"} (props :label)))))

(def Keypad
  (component "Keypad"
    :render (fn [props]
              (element "div" {}
                (element "div" {}
                  (element Button {:label "7"})
                  (element Button {:label "8"})
                  (element Button {:label "9"})
                  (element Button {:label "/"}))
                (element "div" {}
                  (element Button {:label "6"})
                  (element Button {:label "5"})
                  (element Button {:label "4"})
                  (element Button {:label "*"}))
                (element "div" {}
                  (element Button {:label "3"})
                  (element Button {:label "2"})
                  (element Button {:label "1"})
                  (element Button {:label "-"}))
                (element "div" {}
                  (element Button {:label "0"})
                  (element Button {:label "."})
                  (element Button {:label "="})
                  (element Button {:label "+"}))))))

Now we need to make those buttons do something. We’ll start with the digits 0 to 9. When pressed, the digit should be appended to the current number on display. Here’s the event handler. It uses swap! to update the app-state atom.

You can try it out on the REPL.

(defn digit-pressed [digit]
  (swap! app-state update :display #(long (str % digit))))

Change the Button component to accept a “onPress” event handler. When a button is clicked, the event handler is called with the label of the button. We now attach digit-pressed to the buttons 0 to 9.

(def Button
  (component "Button"
    :render (fn [props]
              (let [label (props :label)
                    handler (props :onPress)]
                (element "button" {:className "button"
                                   :onClick #(handler label)} label)))))

(def Keypad
  (component "Keypad"
    :render (fn [props]
              (element "div" {}
                (element "div" {}
                  (element Button {:label "7" :onPress digit-pressed})
                  (element Button {:label "8" :onPress digit-pressed})
                  (element Button {:label "9" :onPress digit-pressed})
                  (element Button {:label "/"}))
                (element "div" {}
                  (element Button {:label "6" :onPress digit-pressed})
                  (element Button {:label "5" :onPress digit-pressed})
                  (element Button {:label "4" :onPress digit-pressed})
                  (element Button {:label "*"}))
                (element "div" {}
                  (element Button {:label "3" :onPress digit-pressed})
                  (element Button {:label "2" :onPress digit-pressed})
                  (element Button {:label "1" :onPress digit-pressed})
                  (element Button {:label "-"}))
                (element "div" {}
                  (element Button {:label "0" :onPress digit-pressed})
                  (element Button {:label "."})
                  (element Button {:label "="})
                  (element Button {:label "+"}))))))

Sweet, we can already enters numbers on our calculator. Let’s have another look at the React browser extension. We can see all our components there, with their properties and children. Very handy for debugging!

Now let’s get this calculator actually calculate. For that we need to keep track of any outstanding calculations. In the app-state, add a :history key, which starts out as an empty vector. Change the defonce to def for a moment so the change gets picked up.

(def app-state (atom {:display 0 :history []}))

Whenever an operator like “+” or “-“ is pressed, we push the current display value onto this history vector together with the operator, and set the display-value to 0 again.

(defn operator-pressed [op]
  (swap! app-state (fn [state]
                     (-> state
                         (update :history #(conj % (:display state) op))
                         (assoc :display 0)))))

(def Keypad
  (component "Keypad"
    :render (fn [props]
              (element "div" {}
                (element "div" {}
                  (element Button {:label "7" :onPress digit-pressed})
                  (element Button {:label "8" :onPress digit-pressed})
                  (element Button {:label "9" :onPress digit-pressed})
                  (element Button {:label "/" :onPress operator-pressed}))
                (element "div" {}
                  (element Button {:label "6" :onPress digit-pressed})
                  (element Button {:label "5" :onPress digit-pressed})
                  (element Button {:label "4" :onPress digit-pressed})
                  (element Button {:label "*" :onPress operator-pressed}))
                (element "div" {}
                  (element Button {:label "3" :onPress digit-pressed})
                  (element Button {:label "2" :onPress digit-pressed})
                  (element Button {:label "1" :onPress digit-pressed})
                  (element Button {:label "-" :onPress operator-pressed}))
                (element "div" {}
                  (element Button {:label "0" :onPress digit-pressed})
                  (element Button {:label "."})
                  (element Button {:label "="})
                  (element Button {:label "+" :onPress operator-pressed}))))))

Let’s hook that up to the History component, so we see what we’re doing. Make sure to require clojure.string :as str as well.

(ns ,,, (:require [clojure.string :as str]))

(def History
  (component "History"
    :render (fn [props]
              (element "div" {:className "history"} (str/join " " (props :history))))))

(def Calculator
  (component "Calculator"
    :render (fn [props]
              (element "div" {}
                (element History {:history (props :history)})
                (element Display {:value (props :display)})
                (element Keypad {})))))

Cool, we’re almost there. All that’s left for us to do is hook up the equals sign. I’ll start with this compute function, which simply performs a list of calculations.

It’s a recursive function. I won’t explain it in detail, but you can try it out on the REPL to see what it does. It willfully ignores precedence rules like some punk rock joyrider.

(defn compute [result & [op num & xs]]
  (case op
    "+" (recur (+ result num) xs)
    "-" (recur (- result num) xs)
    "/" (recur (/ result num) xs)
    "*" (recur (* result num) xs)
    result))

calculator.core> (compute 10 "+" 20 "-" 5)
25

And finally the event handler. It adds the final value on the display to the history, computes and displays the result, and resets the history.

(defn equals-pressed [_]
  (swap! app-state (fn [state]
                     (let [history (conj (:history state) (:display state))
                           result (apply compute history)]
                       (-> state
                           (assoc :display result)
                           (assoc :history []))))))

And that concludes this episode on React. React is built on only a small amount of concepts. The entry point is ReactDOM.render. There are elements and components, which together form the virtual DOM. Components have properties which they receive from their parent component. That’s it.

There are only two things we didn’t discuss. The first is component-local state. Most ClojureScript libraries ignore or avoid it, and so should you. Nevertheless, I’ll leave a note in the Show Notes so at least you know what it is.

The other thing we didn’t discuss in detail are component life cycle methods, besides the mandatory render method. We’ll have a lot more to say about these in future episodes.

I decided not to split this episode up, so it has been longer than usual. Did you like that, or would you have preferred two or three installments, so you get to come up for breath in between episodes? Let me know! You can reach me on Twitter, or via email at arne@lambdaisland.com.

Thanks for watching, and till next time, on Lambda Island!

Show Notes

Code for this episode

github:lambdaisland/react-calculator

Caution

The Chestnut application template has changed since this episode was written. To follow along you are best to stick to version 0.14.0, which you can do like this.

$ lein new chestnut calculator --template-version 0.14.0 -- --vanilla

This unfortunately pulls in a version of rrb-vector which is not compatible with newer versions of Java. To fix that, add this to the :dependencies in project.clj:

[org.clojure/core.rrb-vector "0.0.14"]
[javax.xml.bind/jaxb-api "2.2.4"]

result:

(defproject calculator "0.1.0-SNAPSHOT"
  :dependencies [,,,
                 [org.clojure/core.rrb-vector "0.0.14"]
                 [javax.xml.bind/jaxb-api "2.2.4"]
                 ,,,
                 ]
  ,,,)

React.js

I cover React.js before going into Reagent or Om, because I found it tremendously helpful to understand React first. I remember reading the Om documentation multiple times over. It wouldn’t click until I had gone off and understood React on its own.

The “reference” section of the React docs in particular will continue to come in handy:

Component local state

All the components in this example relied only on their “props”, they are in a sense pure functions: for the same props they will render the same virtual DOM.

React also allows components to keep their own state. You do this inside component lifecycle methods by using this.getState() and this.setState(state). Calling setState will cause React to re-render the component.

A typical example would be a text-field that keeps the currently entered value only in the component.

React itself has little opinion about where you put your state, it is only a view layer after all. The various Clojure libraries that are powered by React do have suggestions on how to handle your application state.

js/Symbol

The Symbol type is part of EcmaScript 6, and is at least partially supported in all current browsers. It plays a role somewhat similar to enums in other languages. Every React component has a $$typeof property containing the same identical Symbol, so React can quickly check if something is an element.

In environments without Symbol, React uses a magic number instead as the value of $$typeof.

The ClojureScript mechanism that powers prn and print is extensible through protocols, that’s why we can use this snippet to add our serialization for Symbols.

(extend-type js/Symbol
  IPrintWithWriter
  (-pr-writer [obj writer _]
    (write-all writer (str "#object[" (.toString obj) "]"))))